{"id":16426266,"url":"https://github.com/zipfian-science/rickled","last_synced_at":"2025-03-28T22:30:46.331Z","repository":{"id":43209738,"uuid":"300628402","full_name":"Zipfian-Science/rickled","owner":"Zipfian-Science","description":"Rickle, a loose stack/pile; Rickle is a Python tool for easy to use configuration with YAML/JSON files","archived":false,"fork":false,"pushed_at":"2024-10-29T12:39:54.000Z","size":435,"stargazers_count":8,"open_issues_count":9,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-30T08:20:42.800Z","etag":null,"topics":["configuration","yaml"],"latest_commit_sha":null,"homepage":"http://rickle.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Zipfian-Science.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-10-02T13:46:29.000Z","updated_at":"2024-10-08T21:30:49.000Z","dependencies_parsed_at":"2023-12-13T09:48:27.226Z","dependency_job_id":"cfea376b-907b-47c3-a0de-73d857203473","html_url":"https://github.com/Zipfian-Science/rickled","commit_stats":{"total_commits":44,"total_committers":4,"mean_commits":11.0,"dds":0.5227272727272727,"last_synced_commit":"3a2aaa6af6d26e5345b6e8687ab733997aebd078"},"previous_names":["zipfian-science/pickle-rick","zipfian-science/rickle"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zipfian-Science%2Frickled","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zipfian-Science%2Frickled/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zipfian-Science%2Frickled/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zipfian-Science%2Frickled/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Zipfian-Science","download_url":"https://codeload.github.com/Zipfian-Science/rickled/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":222422267,"owners_count":16981940,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["configuration","yaml"],"created_at":"2024-10-11T08:08:03.705Z","updated_at":"2025-03-28T22:30:46.323Z","avatar_url":"https://github.com/Zipfian-Science.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# rickle - Smart Python tools for working with Configs\n\n![PyPI - Version](https://img.shields.io/pypi/v/rickled)\n[![Downloads](https://static.pepy.tech/badge/rickled)](https://pepy.tech/project/rickled)\n[![Downloads](https://static.pepy.tech/badge/rickled/month)](https://pepy.tech/project/rickled)\n[![General badge](https://img.shields.io/badge/Coverage-75+-\u003cCOLOR\u003e.svg)](https://zipfian.science/docs/rickle/coverage/index.html)\n\n---\n\n```\n██████╗ ██╗ ██████╗██╗  ██╗██╗     ███████╗\n██╔══██╗██║██╔════╝██║ ██╔╝██║     ██╔════╝\n██████╔╝██║██║     █████╔╝ ██║     █████╗  \n██╔══██╗██║██║     ██╔═██╗ ██║     ██╔══╝  \n██║  ██║██║╚██████╗██║  ██╗███████╗███████╗\n╚═╝  ╚═╝╚═╝ ╚═════╝╚═╝  ╚═╝╚══════╝╚══════╝\n                                           \nby Zipfian Science                               \n```\n\n---\n\n`rickle` is a versatile Python library and command-line tool that offers a wide range of functionalities for working with YAML and JSON (and TOML, INI, XML, .ENV) data\n\n1. **Serialization**: `rickle` allows you to easily serialize Python objects to text formats like YAML or JSON. \nThis is particularly useful for converting Python data structures into a human-readable and easily shareable format, such as `config` files.\n\n2. **Schema Validation**: It provides the capability to validate YAML (and JSON, etc.) data against predefined schemas. This ensures that your data adheres to a specific structure or format, helping to maintain data consistency.\n\n3. **Schema Generation**: Start with easy schema definition generations from existing config files. This is helpful when you want to formalize the structure of your data or for documentation purposes.\n\n4. **Conversion**: `rickle` offers seamless conversion between YAML, JSON, INI, XML, and .ENV formats. This facilitates data interchange between systems that use different serialization formats.\n\n5. **Simple Web Server**: An experimental unique feature of `rickle` is its ability to create a basic web server from a YAML (or JSON, TOML, XML, INI) file. This means you can define endpoints, routes, and data sources purely by writing it as a YAML/etc. file, making it easy to prototype web services without extensive coding, or to create mock REST APIs, or even to serve configuration files as REST APIs. \n\n`rickle` is a powerful utility for working with configuration data in Python. \nIt simplifies tasks like serialization, schema validation, schema generation, format conversion, \nand even enables quick web server prototyping. \nThis tool is valuable for developers and data engineers working \nwith structured data in a flexible and efficient manner.\n\n---\n\n# Usage\n\nFor usage examples see [examples](https://zipfian.science/docs/rickle/examples.html) page. \nDocumentation can be [found here](https://zipfian.science/docs/rickle/index.html). \n\n## 1. Install\n\nFirst install the tool (Python version \u003e= 3.9):\n\n```bash script\n$ pip install rickle\n```\n---\n### 1.1 Extras\n\nOptionally the twisted web server can be installed alongside for the `serve` functionality.\n\n```bash script\n$ pip install rickle[net]\n```\n\nFor expanded schema validators.\n\n```bash script\n$ pip install rickle[validators]\n```\n\nFor xml support.\n\n```bash script\n$ pip install rickle[xml]\n```\n\nFor .env file support.\n\n```bash script\n$ pip install rickle[dotenv]\n```\n\nFor a fully featured install.\n\n```bash script\n$ pip install rickle[full]\n```\n\nCheck if the installation succeeded:\n\n```bash script\n$ rickle --help\n```\n\n## 2. And use\n\n```python\nfrom rickle import Rickle\n```\n\nUsing an example YAML file:\n\n```yaml\nconf:\n  db_connection:\n     acc_name:\n        type: env\n        load: ACC_NAME\n        default: developer_account\n     acc_pass:\n        type: env\n        load: ACC_PASS\n     database_name: public\n```\n\nThen use Rickle:\n\n```python\n\u003e\u003e config = Rickle('./config.yaml')\n\n\u003e\u003e config.conf.db_connection.dict()\n{'acc_name' : 'acceptance_account', 'acc_pass' : 'asd!424iXj', 'database_name' : 'public'}\n\n\u003e\u003e config.conf.db_connection.acc_pass\n'asd!424iXj'\n\n\u003e\u003e config('/conf/db_connection/acc_pass')\n'asd!424iXj'\n```\n\n\n---\n## 3. Schema tools\n\nTwo main schema tools exist, the `check` and the `gen` tools.\n\n---\n\n### 3.1 Schema `check`\n\nFor checking the schema of input files, the `check` tool is used.\n\n```bash script\n$ rickle schema check --help\n```\n\n```bash script\n$ rickle schema check --input test.yaml --schema schema.yaml \n```\n\nOR\n\n```bash script\n$ cat test.yaml | rickle schema check --schema schema.yaml \n```\n\n---\n\n### 3.2 Schema `gen`\n\nSchema files can be generated from YAML files with the `gen` tool.\n\n```bash script\n$ rickle schema gen --help\n```\n\n```bash script\n$ rickle schema gen --input test.yaml\n```\n\nThis will generate a schema file called `test.schema.yaml`.\n\nOR\n\n```bash script\n$ cat test.yaml | rickle schema --output-type json gen\n```\n\nThis will generate a schema and print the output, in this example in JSON.\n\n---\n\n## 4. Conversion tools\n\n`rickle` can also be used for bulk conversion from YAML to JSON or the other way around.\n\n```bash script\n$ rickle conv --help\n```\n\nTo convert input files (or directories):\n\n```bash script\n$ rickle conv --input test.yaml --output test.json\n```\n\nFor each input file the output file can be defined and the path suffix is used to infer the desired output type.\nUsing input and output will read and write to files. Alternatively:\n\n```bash script\n$ cat text.yaml | rickle --output-type json conv \n```\n\nThe output type can be specified with the `--output-type` flag.\n\n---\n\n## 5. `object` functions\n\nCertain `jq` like functionality can be achieved using `rickle`. This includes the ability to `get`, `set`, `del`, and `search`\ndocument paths. This is done using the object tool `obj`.\n\nTo see more:\n\n```bash script\n$ rickle obj --help\n```\n```bash script\n$ rickle obj get --help\n```\n```bash script\n$ rickle obj set --help\n```\n```bash script\n$ rickle obj put --help\n```\n```bash script\n$ rickle obj del --help\n```\n```bash script\n$ rickle obj search --help\n```\n```bash script\n$ rickle obj find --help\n```\n---\n\n### 5.1 Paths\n\nTo get to a specific value, a path is traversed. This path looks much like a Unix or web path.\nTo get the whole document, `/` is used. Expanding the path would look something like this: \n\n```yaml\npath:\n  to:\n    value: \"hello world\"\n```\nThe path `/path/to/value` would yield the string `hello world`.\n\n```yaml\npath:\n  to:\n    value: \"hello world\"\n    values:\n      - one\n      - two\n      - three\n```\n\nWorking with lists is possible with indices, for example `/path/to/values/[0]` would yield the string `one`. \nAnd the path `/path/to` would yield:\n\n```yaml\nvalue: \"hello world\"\nvalues:\n  - one\n  - two\n  - three\n```\n\n\u003e **_NOTE:_**  It is possible to change the path separator by setting the env variable `RICKLE_PATH_SEP`.\n\n---\n\n### 5.2 Get\n\n```bash script\n$ rickle obj --input test.yaml get /\n```\n\nOR\n\n```bash script\n$ cat test.yaml | rickle obj get /\n```\n\nThis will output the entire test.yaml. If the path, using the above example with path `/path/to/values/[0]`, the output will \nsimply be `one`.\n\n---\n\n### 5.2 Set\n\n```bash script\n$ rickle obj --input test.yaml set /path/to/values/[1] foo\n```\n\nOR\n\n```bash script\n$ cat test.yaml | rickle obj set /path/to/values/[1] foo\n```\n\nwill output the following: \n\n```yaml\npath:\n  to:\n    value: \"hello world\"\n    values:\n      - one\n      - foo\n      - three\n```\n\n\u003e [!NOTE]\n\u003e To put a value with a path that does not exist (i.e. create the path) use `put`\n\n---\n\n### 5.3 Put\n\n```bash script\n$ rickle obj --input test.yaml put /path/to/non/existing bar\n```\n\nOR\n\n```bash script\n$ cat test.yaml | rickle put /path/to/non/existing bar\n```\n\nwill output the following: \n\n```yaml\npath:\n  to:\n    non:\n      existing: bar\n    value: \"hello world\"\n    values:\n      - one\n      - two\n      - three\n```\n\n---\n\n### 5.4 Search\n\nConsider the following:\n\n```yaml\npath:\n  to:\n    key: \"hello world\"\n  and:\n    another:\n      key: \"ok go\"\n```\n\nDocument paths can be searched:\n\n```bash script\n$ rickle obj --input test.yaml search key\n```\n\nOR\n\n```bash script\n$ cat test.yaml | rickle obj search key\n```\n\nWill output the following (in YAML):\n\n```\n- /path/to/key\n- /path/and/another/key\n```\n\nDifferent output types are passed with the `--output-type` flag, including the `array` type to print paths as lines. \n\n```bash script\n$ cat test.yaml | rickle --output-type list obj search key\n```\n\nWill instead output the following:\n\n```\n/path/to/key\n/path/and/another/key\n```\n\n---\n\n### 5.5 Find\n\nAlternative to search where a key with a matching value (condition) is \"found\":\n\nConsider the file `arr-dev.jsonl`:\n\n```json lines\n{\"name\": \"Lindsay\", \"surname\": \"Funke\", \"score\": 29}\n{\"name\": \"Gob\", \"surname\": \"Bluth\", \"score\": 14}\n{\"name\": \"Tobias\", \"surname\": \"Funke\", \"score\": 19}\n{\"name\": \"Buster\", \"surname\": \"Bluth\", \"score\": 25}\n```\n\nUsing the find tool: \n\n```bash script\ncat arr-dev.jsonl | rickle obj find \"surname = Bluth\" \n```\n\noutputs \n\n```\n/[1]/surname\n/[3]/surname\n```\n\nExamples of using find:\n\n```bash script\ncat arr-dev.jsonl | rickle obj find --or \"score \u003c 19\" \"score \u003e 25\"\ncat arr-dev.jsonl | rickle obj find --and \"score \u003e 14\" \"score \u003c 20\"\ncat arr-dev.jsonl | rickle obj find --and \"surname = Bluth\" \"score \u003c 20\" -p\n```\n\n---\n\n## 6. Serving via HTTP(s)\n\nA nifty little use of this Python tool is the ability to host a webserver, using a YAML (or other) file.\nFor this functionality to work the \"net\" extras need to be installed, `pip install rickel[net]`.  \n \n```bash script\n$ rickle serve --help\n```\n\n```bash script\n$ rickle serve --input basic_example.yaml\n```\n\nOR\n\n```bash script\n$ cat basic_example.yaml | rickle serve\n```\n\nThis will start listening on http://localhost:8080, for requests using `GET`. \n\nAlternatively serve through SSL:\n\n```bash script\n$ cat basic_example.yaml | rickle serve --certificate ./certificate.crt --private-key ./privkey.pem\n```\n\nThis will start listening on https://localhost:8080. \n\nFurthermore, define host or port:\n\n```bash script\n$ cat basic_example.yaml | rickle serve --host \"0.0.0.0\" --port 8077\n```\n\nThis will start listening on https://0.0.0.0:8077. \n\nAutomatically open a new browser tab:\n\n```bash script\n$ cat basic_example.yaml | rickle serve -b\n```\n\nAdd Python functions to the YAML file (unsafe!):\n\n\u003e **_CAUTION:_**  Using `--unsafe` should only be used on trusted data.\n\n```bash script\n$ export RICKLE_UNSAFE_LOAD=1\n$ cat unsafe_example.yaml | rickle serve --unsafe --load-lambda\n```\n\nThis will start listening on http://localhost:8080, \nand if there are Python functions defined in the YAML file, these will be executable. \nThis holds **security risks** though, and should only be used with caution.\n\n---\n\n# Release\n\nSee the version history in [changelog](https://zipfian.science/docs/rickle/changelog.html).\n\n\n---\n\n# Contributing\n\nAs this is an open source project, forks and PRs are welcome! \nPlease review some of the practices stated in [CONTRIBUTIONS.md](https://github.com/Zipfian-Science/rickled/blob/master/CONTRIBUTING.md).\n\n---\n\n© [Zipfian Science](https://zipfian.science) 2020 - 2025\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzipfian-science%2Frickled","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzipfian-science%2Frickled","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzipfian-science%2Frickled/lists"}