| Name | rickled JSON |
| Version |
1.2.0
JSON |
| download |
| home_page | None |
| Summary | Tools for pickling Python objects in a completely different way |
| upload_time | 2025-02-03 22:39:32 |
| maintainer | None |
| docs_url | None |
| author | Zipfian Science |
| requires_python | >=3.9 |
| license | Apache 2.0 |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# rickle - Smart Python tools for working with Configs
[](https://pepy.tech/project/rickled)
[](https://pepy.tech/project/rickled)
[](https://zipfian.science/docs/rickle/coverage/index.html)
---
```
██████╗ ██╗ ██████╗██╗ ██╗██╗ ███████╗
██╔══██╗██║██╔════╝██║ ██╔╝██║ ██╔════╝
██████╔╝██║██║ █████╔╝ ██║ █████╗
██╔══██╗██║██║ ██╔═██╗ ██║ ██╔══╝
██║ ██║██║╚██████╗██║ ██╗███████╗███████╗
╚═╝ ╚═╝╚═╝ ╚═════╝╚═╝ ╚═╝╚══════╝╚══════╝
by Zipfian Science
```
---
`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
1. **Serialization**: `rickle` allows you to easily serialize Python objects to text formats like YAML or JSON.
This is particularly useful for converting Python data structures into a human-readable and easily shareable format, such as `config` files.
2. **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.
3. **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.
4. **Conversion**: `rickle` offers seamless conversion between YAML, JSON, INI, XML, and .ENV formats. This facilitates data interchange between systems that use different serialization formats.
5. **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.
`rickle` is a powerful utility for working with configuration data in Python.
It simplifies tasks like serialization, schema validation, schema generation, format conversion,
and even enables quick web server prototyping.
This tool is valuable for developers and data engineers working
with structured data in a flexible and efficient manner.
---
# Usage
For usage examples see [examples](https://zipfian.science/docs/rickle/examples.html) page.
Documentation can be [found here](https://zipfian.science/docs/rickle/index.html).
## 1. Install
First install the tool (Python version >= 3.9):
```bash script
$ pip install rickled
```
---
### 1.1 Extras
Optionally the twisted web server can be installed alongside for the `serve` functionality.
```bash script
$ pip install rickled[net]
```
For expanded schema validators.
```bash script
$ pip install rickled[validators]
```
For xml support.
```bash script
$ pip install rickled[xml]
```
For .env file support.
```bash script
$ pip install rickled[dotenv]
```
For a fully featured install.
```bash script
$ pip install rickled[full]
```
Check if the installation succeeded:
```bash script
$ rickle --help
```
## 2. And use
```python
from rickled import Rickle
```
Using an example YAML file:
```yaml
conf:
db_connection:
acc_name:
type: env
load: ACC_NAME
default: developer_account
acc_pass:
type: env
load: ACC_PASS
database_name: public
```
Then use Rickle:
```python
>> config = Rickle('./config.yaml')
>> config.conf.db_connection.dict()
{'acc_name' : 'acceptance_account', 'acc_pass' : 'asd!424iXj', 'database_name' : 'public'}
>> config.conf.db_connection.acc_pass
'asd!424iXj'
>> config('/conf/db_connection/acc_pass')
'asd!424iXj'
```
---
## 3. Schema tools
Two main schema tools exist, the `check` and the `gen` tools.
---
### 3.1 Schema `check`
For checking the schema of input files, the `check` tool is used.
```bash script
$ rickle schema check --help
```
```bash script
$ rickle schema check --input test.yaml --schema schema.yaml
```
OR
```bash script
$ cat test.yaml | rickle schema check --schema schema.yaml
```
---
### 3.2 Schema `gen`
Schema files can be generated from YAML files with the `gen` tool.
```bash script
$ rickle schema gen --help
```
```bash script
$ rickle schema gen --input test.yaml
```
This will generate a schema file called `test.schema.yaml`.
OR
```bash script
$ cat test.yaml | rickle schema --output-type json gen
```
This will generate a schema and print the output, in this example in JSON.
---
## 4. Conversion tools
`rickle` can also be used for bulk conversion from YAML to JSON or the other way around.
```bash script
$ rickle conv --help
```
To convert input files (or directories):
```bash script
$ rickle conv --input test.yaml --output test.json
```
For each input file the output file can be defined and the path suffix is used to infer the desired output type.
Using input and output will read and write to files. Alternatively:
```bash script
$ cat text.yaml | rickle --output-type json conv
```
The output type can be specified with the `--output-type` flag.
---
## 5. `object` functions
Certain `jq` like functionality can be achieved using `rickle`. This includes the ability to `get`, `set`, `del`, and `search`
document paths. This is done using the object tool `obj`.
To see more:
```bash script
$ rickle obj --help
```
```bash script
$ rickle obj get --help
```
```bash script
$ rickle obj set --help
```
```bash script
$ rickle obj del --help
```
```bash script
$ rickle obj search --help
```
---
### 5.1 Paths
To get to a specific value, a path is traversed. This path looks much like a Unix or web path.
To get the whole document, `/` is used. Expanding the path would look something like this:
```yaml
path:
to:
value: "hello world"
```
The path `/path/to/value` would yield the string `hello world`.
```yaml
path:
to:
value: "hello world"
values:
- one
- two
- three
```
Working with lists is possible with indices, for example `/path/to/values/[0]` would yield the string `one`.
And the path `/path/to` would yield:
```yaml
value: "hello world"
values:
- one
- two
- three
```
> **_NOTE:_** It is possible to change the path separator by setting the env variable `RICKLE_PATH_SEP`.
---
### 5.2 Get
```bash script
$ rickle obj --input test.yaml get /
```
OR
```bash script
$ cat test.yaml | rickle obj get /
```
This will output the entire test.yaml. If the path, using the above example with path `/path/to/values/[0]`, the output will
simply be `one`.
---
### 5.2 Set
```bash script
$ rickle obj --input test.yaml set /path/to/values/[1] foo
```
OR
```bash script
$ cat test.yaml | rickle obj set /path/to/values/[1] foo
```
will output the following:
```yaml
path:
to:
value: "hello world"
values:
- one
- foo
- three
```
---
### 5.3 Search
Consider the following:
```yaml
path:
to:
key: "hello world"
and:
another:
key: "ok go"
```
Document paths can be searched:
```bash script
$ rickle obj --input test.yaml search key
```
OR
```bash script
$ cat test.yaml | rickle obj search key
```
Will output the following (in YAML):
```
- /path/to/key
- /path/and/another/key
```
Different output types are passed with the `--output-type` flag, including the `list` type to print paths as lines.
```bash script
$ cat test.yaml | rickle --output-type list obj search key
```
Will instead output the following:
```
/path/to/key
/path/and/another/key
```
---
## 6. Serving via HTTP(s)
A nifty little use of this Python tool is the ability to host a webserver, using a YAML (or other) file.
```bash script
$ rickle serve --help
```
```bash script
$ rickle serve --input basic_example.yaml
```
OR
```bash script
$ cat basic_example.yaml | rickle serve
```
This will start listening on http://localhost:8080, for requests using `GET`.
Alternatively serve through SSL:
```bash script
$ cat basic_example.yaml | rickle serve --certificate ./certificate.crt --private-key ./privkey.pem
```
This will start listening on https://localhost:8080.
Furthermore, define host or port:
```bash script
$ cat basic_example.yaml | rickle serve --host "0.0.0.0" --port 8077
```
This will start listening on https://0.0.0.0:8077.
Automatically open a new browser tab:
```bash script
$ cat basic_example.yaml | rickle serve -b
```
Add Python functions to the YAML file (unsafe!):
> **_CAUTION:_** Using `--unsafe` should only be used on trusted data.
```bash script
$ export RICKLE_UNSAFE_LOAD=1
$ cat unsafe_example.yaml | rickle serve --unsafe --load-lambda
```
This will start listening on http://localhost:8080,
and if there are Python functions defined in the YAML file, these will be executable.
This holds **security risks** though, and should only be used with caution.
---
# Release
See the version history in [changelog](https://zipfian.science/docs/rickle/changelog.html).
---
# Contributing
As this is an open source project, forks and PRs are welcome!
Please review some of the practices stated in [CONTRIBUTIONS.md](https://github.com/Zipfian-Science/rickled/blob/master/CONTRIBUTING.md).
---
© [Zipfian Science](https://zipfian.science) 2020 - 2025
Raw data
{
"_id": null,
"home_page": null,
"name": "rickled",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Zipfian Science",
"author_email": null,
"download_url": null,
"platform": null,
"description": "# rickle - Smart Python tools for working with Configs\n\n\n[](https://pepy.tech/project/rickled)\n[](https://pepy.tech/project/rickled)\n[](https://zipfian.science/docs/rickle/coverage/index.html)\n\n---\n\n```\n\u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2557 \u2588\u2588\u2557\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\n\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557\u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255d\u2588\u2588\u2551 \u2588\u2588\u2554\u255d\u2588\u2588\u2551 \u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255d\n\u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255d\u2588\u2588\u2551\u2588\u2588\u2551 \u2588\u2588\u2588\u2588\u2588\u2554\u255d \u2588\u2588\u2551 \u2588\u2588\u2588\u2588\u2588\u2557 \n\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557\u2588\u2588\u2551\u2588\u2588\u2551 \u2588\u2588\u2554\u2550\u2588\u2588\u2557 \u2588\u2588\u2551 \u2588\u2588\u2554\u2550\u2550\u255d \n\u2588\u2588\u2551 \u2588\u2588\u2551\u2588\u2588\u2551\u255a\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2551 \u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\n\u255a\u2550\u255d \u255a\u2550\u255d\u255a\u2550\u255d \u255a\u2550\u2550\u2550\u2550\u2550\u255d\u255a\u2550\u255d \u255a\u2550\u255d\u255a\u2550\u2550\u2550\u2550\u2550\u2550\u255d\u255a\u2550\u2550\u2550\u2550\u2550\u2550\u255d\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 >= 3.9):\n\n```bash script\n$ pip install rickled\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 rickled[net]\n```\n\nFor expanded schema validators.\n\n```bash script\n$ pip install rickled[validators]\n```\n\nFor xml support.\n\n```bash script\n$ pip install rickled[xml]\n```\n\nFor .env file support.\n\n```bash script\n$ pip install rickled[dotenv]\n```\n\nFor a fully featured install.\n\n```bash script\n$ pip install rickled[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 rickled 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>> config = Rickle('./config.yaml')\n\n>> config.conf.db_connection.dict()\n{'acc_name' : 'acceptance_account', 'acc_pass' : 'asd!424iXj', 'database_name' : 'public'}\n\n>> config.conf.db_connection.acc_pass\n'asd!424iXj'\n\n>> 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 del --help\n```\n```bash script\n$ rickle obj search --help\n```\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> **_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---\n\n### 5.3 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 `list` 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## 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.\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> **_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\u00a9 [Zipfian Science](https://zipfian.science) 2020 - 2025\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "Tools for pickling Python objects in a completely different way",
"version": "1.2.0",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9ac964c1f6fba597ae59013df51899acaec45e7f41a61c4b985ae6f51441bbc7",
"md5": "73cd308da2849738eaf5f6474aa83afd",
"sha256": "036b9432a9ef9cc45c67c6074942fda8d89c6291b92d64f3f3ab83ffa832a8c9"
},
"downloads": -1,
"filename": "rickled-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "73cd308da2849738eaf5f6474aa83afd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 47877,
"upload_time": "2025-02-03T22:39:32",
"upload_time_iso_8601": "2025-02-03T22:39:32.598137Z",
"url": "https://files.pythonhosted.org/packages/9a/c9/64c1f6fba597ae59013df51899acaec45e7f41a61c4b985ae6f51441bbc7/rickled-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-03 22:39:32",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "rickled"
}
