Ycleptic

Self-documenting YAML configuration for Python applications

PyPI Python versions CI Documentation Status License: MIT

One structured YAML file describes your application's configuration schema. From that single source of truth, Ycleptic gives you three things that normally live in three separate places:

  1. Validation & defaults — a user's YAML config is checked against the schema (allowed keys, data types, choices, required values), and omitted parameters are filled in from their declared defaults.
  2. Generated documentation — yclept make-doc builds an RST/Sphinx documentation tree for your config directly from the schema.
  3. Interactive help — yclept config-help lets users explore the configuration tree and read the help text for every parameter.

Because the schema is data — a YAML file you ship as package data, not a set of Python classes — editing that one file keeps validation, documentation, and help in lockstep. No more reference docs drifting out of date because you added a parameter and forgot to write it up.

When to use it

Ycleptic fills a specific niche: it shines when your configuration's schema should double as its documentation, and when your users benefit from exploring that configuration interactively — a common situation in scientific and command-line applications whose users are domain experts rather than programmers.

It is intentionally not a heavyweight validation engine. If your main need is:

  • robust validation, coercion, and rich error messages — reach for pydantic or jsonschema;
  • composable, hierarchical config with overrides and interpolation — reach for Hydra / OmegaConf.

Ycleptic keeps validation deliberately lightweight and puts its weight behind the spec-as-documentation workflow. (It also supports a per-user dotfile/rcfile that extends or overrides the base config, merged in automatically at load time.)

How it works

As the developer, you write a base config that specifies what your users may configure:

# mypackage/data/base.yaml
attributes:
  - name: temperature
    type: float
    text: Simulation temperature in kelvin
    default: 300.0
  - name: integrator
    type: str
    text: Integration scheme to use
    choices: [verlet, langevin]
    default: verlet

Your app reads the base config together with the user's config through the Yclept class (typically subclassed):

from ycleptic import Yclept, YclepticError

try:
    config = Yclept(basefile='mypackage/data/base.yaml', userfile=user_yaml)
except YclepticError as e:
    raise SystemExit(f'Invalid configuration: {e}')

Then, from the same base config, you can generate reference documentation:

yclept make-doc mypackage/data/base.yaml --root docs/source/config_ref

and your users can explore the configuration interactively:

yclept config-help mypackage/data/base.yaml

Installation

pip install ycleptic

Documentation

Full documentation is at https://ycleptic.readthedocs.io/en/latest/.

Release History

See CHANGELOG.md for the full release history.

Meta

Cameron F. Abrams – cfa22@drexel.edu

Distributed under the MIT license. See LICENSE for more information.

https://github.com/cameronabrams

https://github.com/AbramsGroup

Contributing

  1. Fork it (https://github.com/cameronabrams/ycleptic/fork)
  2. Create your feature branch (git checkout -b feature/fooBar)
  3. Commit your changes (git commit -am 'Add some fooBar')
  4. Push to the branch (git push origin feature/fooBar)
  5. Create a new Pull Request

Project links

Data verified by PyPI on Aug 13, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for cameronabrams from gravatar.com cameronabrams

Credits

PyPI data
Data sourced directly from PyPI's database.

Author: Cameron F Abrams

GitHub Statistics

Data verified by PyPI on Aug 13, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT License)

Requires

Python >=3.9

Provides Extra

lint test

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ycleptic-2.3.0.tar.gz (43.6 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

ycleptic-2.3.0-py3-none-any.whl (23.1 kB view details)

Uploaded Python 3

File details

Details for the file ycleptic-2.3.0.tar.gz.

File metadata

  • Download URL: ycleptic-2.3.0.tar.gz
  • Upload date:
  • Size: 43.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for ycleptic-2.3.0.tar.gz
Algorithm Hash digest
SHA256 9e0d32a217d51a97d47c1944261e0ba697d303d661ec6f4db2a4d3ab8d8ee243
MD5 3468037a382224035323aaab4447707e
BLAKE2b-256 bc5bf3be2ee27246fc2e8f0fa423d0ecce7b41cedea7ef0833f504b62c061017

See more details on using hashes here.

Provenance

The following attestation bundles were made for ycleptic-2.3.0.tar.gz:

Publisher: release.yaml on cameronabrams/ycleptic

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ycleptic-2.3.0-py3-none-any.whl.

File metadata

  • Download URL: ycleptic-2.3.0-py3-none-any.whl
  • Upload date:
  • Size: 23.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for ycleptic-2.3.0-py3-none-any.whl
Algorithm Hash digest
SHA256 98b4a3975f8cbd6e090cc7d9f9d4fd545fc43b272ec6d45558a6a21d2ce3b256
MD5 fb02fc434d860ec65cd6c44eb043009c
BLAKE2b-256 4790c8dbc1b74b6e642827c3d2e47084286856b59baec23e71f5f1b9354593e4

See more details on using hashes here.

Provenance

The following attestation bundles were made for ycleptic-2.3.0-py3-none-any.whl:

Publisher: release.yaml on cameronabrams/ycleptic

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

2.3.0 This release

2 files

2.2.2

2 files

2.2.1

2 files

2.2.0

2 files

2.1.0

2 files

2.0.6

2 files

2.0.5

2 files

2.0.4

2 files

2.0.3

2 files

2.0.2

2 files

2.0.1

2 files

1.9.0

2 files

1.8.1

2 files

1.8.0

2 files

1.7.0

2 files

1.6.2

2 files

1.6.1

2 files

1.5.0

2 files

1.4.1

2 files

1.4.0

2 files

1.3.0

2 files

1.2.0

2 files

1.1.0

2 files

1.0.9

2 files

1.0.8

2 files

1.0.7

2 files

1.0.6

2 files

1.0.5

2 files

1.0.4

2 files

1.0.3.3

2 files

1.0.3.2

2 files

1.0.3.1

2 files

1.0.3

2 files

1.0.2

2 files

1.0.1

2 files

1.0.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page