rickle - Smart Python tools for working with Configs

---

██████╗ ██╗ ██████╗██╗  ██╗██╗     ███████╗
██╔══██╗██║██╔════╝██║ ██╔╝██║     ██╔════╝
██████╔╝██║██║     █████╔╝ ██║     █████╗  
██╔══██╗██║██║     ██╔═██╗ ██║     ██╔══╝  
██║  ██║██║╚██████╗██║  ██╗███████╗███████╗
╚═╝  ╚═╝╚═╝ ╚═════╝╚═╝  ╚═╝╚══════╝╚══════╝
                                           
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 page. Documentation can be found here.

1. Install

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

$ pip install rickle

---

1.1 Extras

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 install.

$ pip install rickle[full]

Check if the installation succeeded:

$ rickle --help

2. And use

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'

---

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.

$ rickle schema check --help

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

OR

$ 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.

$ 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.

---

4. Conversion tools

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.

---

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:

$ rickle obj --help

$ rickle obj get --help

$ rickle obj set --help

$ rickle obj del --help

$ 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:

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

NOTE: It is possible to change the path separator by setting the env variable RICKLE_PATH_SEP.

---

5.2 Get

$ 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.

---

5.2 Set

$ 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

---

5.3 Search

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

---

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.

$ 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!):

CAUTION: Using --unsafe should only be used on trusted data.

$ 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.

---

Contributing

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

---

© Zipfian Science 2020 - 2025