██████╗ ██╗ ██████╗██╗  ██╗██╗     ███████╗
██╔══██╗██║██╔════╝██║ ██╔╝██║     ██╔════╝
██████╔╝██║██║     █████╔╝ ██║     █████╗  
██╔══██╗██║██║     ██╔═██╗ ██║     ██╔══╝  
██║  ██║██║╚██████╗██║  ██╗███████╗███████╗
╚═╝  ╚═╝╚═╝ ╚═════╝╚═╝  ╚═╝╚══════╝╚══════╝
                                                                                                                       
by Zipfian.sh                             

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.

For usage examples see examples page. Documentation can be found here.

First install the tool (Python version >= 3.9):

pip install rickle

Optionally the twisted web server can be installed alongside for the serve functionality.

pip install rickle[net]

For expanded schema validators.

pip install rickle[validators]

For xml support.

pip install rickle[xml]

For .env file support.

pip install rickle[dotenv]

For a fully featured installation.

pip install rickle[full]

Check if the installation succeeded:

rickle --help

from rickle import Rickle

Using an example YAML file:

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:

>> 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'

Two main schema tools exist, the check and the gen tools.

For checking the schema of input files, the check tool is used.

rickle schema check --help

rickle schema check --input test.yaml --schema schema.yaml 

OR

cat test.yaml | rickle schema check --schema schema.yaml 

Schema files can be generated from YAML files with the gen tool.

rickle schema gen --help

rickle schema gen --input test.yaml

This will generate a schema file called test.schema.yaml.

OR

cat test.yaml | rickle schema --output-type json gen

This will generate a schema and print the output, in this example in JSON.

rickle can also be used for bulk conversion from YAML to JSON or the other way around.

rickle conv --help

To convert input files (or directories):

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:

cat text.yaml | rickle --output-type json conv 

The output type can be specified with the --output-type flag.

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:

rickle obj --help

rickle obj get --help

rickle obj set --help

rickle obj put --help

rickle obj del --help

rickle obj search --help

rickle obj find --help

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:

path:
  to:
    value: "hello world"

The path /path/to/value would yield the string hello world.

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:

value: "hello world"
values:
  - one
  - two
  - three

rickle obj --input test.yaml get /

OR

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.

Example using url:

echo https://official-joke-api.appspot.com/random_joke | rickle obj get /

rickle obj --input test.yaml set /path/to/values/[1] foo

OR

cat test.yaml | rickle obj set /path/to/values/[1] foo

will output the following:

path:
  to:
    value: "hello world"
    values:
      - one
      - foo
      - three

rickle obj --input test.yaml put /path/to/non/existing bar

OR

cat test.yaml | rickle put /path/to/non/existing bar

will output the following:

path:
  to:
    non:
      existing: bar
    value: "hello world"
    values:
      - one
      - two
      - three

Consider the following:

path:
  to:
    key: "hello world"
  and:
    another:
      key: "ok go"

Document paths can be searched:

rickle obj --input test.yaml search key

OR

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 array type to print paths as lines.

cat test.yaml | rickle --output-type list obj search key

Will instead output the following:

/path/to/key
/path/and/another/key

Alternative to search where a key with a matching value (condition) is "found":

Consider the file arr-dev.jsonl:

{"name": "Lindsay", "surname": "Funke", "score": 29}
{"name": "Gob", "surname": "Bluth", "score": 14}
{"name": "Tobias", "surname": "Funke", "score": 19}
{"name": "Buster", "surname": "Bluth", "score": 25}

Using the find tool:

cat arr-dev.jsonl | rickle obj find "surname = Bluth" 

outputs

/[1]/surname
/[3]/surname

Examples of using find:

cat arr-dev.jsonl | rickle obj find --or "score < 19" "score > 25"
cat arr-dev.jsonl | rickle obj find --and "score > 14" "score < 20"
cat arr-dev.jsonl | rickle obj find --and "surname = Bluth" "score < 20" -p

A nifty little use of this Python tool is the ability to host a webserver, using a YAML (or other) file. For this functionality to work the "net" extras need to be installed, pip install rickel[net].

rickle serve --help

rickle serve --input basic_example.yaml

OR

cat basic_example.yaml | rickle serve

This will start listening on http://localhost:8080, for requests using GET.

Alternatively serve through SSL:

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:

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:

cat basic_example.yaml | rickle serve -b

Add Python functions to the YAML file (unsafe!):

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 serious security risks though, and should only be used with caution.

See the version history in changelog.

As this is an open source project, forks and PRs are welcome! Please review some of the practices stated in CONTRIBUTIONS.md.

© Zipfian.sh 2020 - 2025