Ycleptic

Self-documenting YAML configuration for Python applications

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 Jul 21, 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:
Newer release available (2.3.0)

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 Jul 21, 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.2.1.tar.gz (37.5 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.2.1-py3-none-any.whl (19.8 kB view details)

Uploaded Python 3

File details

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

File metadata

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

File hashes

Hashes for ycleptic-2.2.1.tar.gz
Algorithm Hash digest
SHA256 435ad015e74244a7c89d28fcf0ba9077374a5d75b60231fb874e732837159c24
MD5 0a2cbe87c3de1c8b73d0eea2ff66b702
BLAKE2b-256 b6ca8e2046977eeedceaaa0eaf802f34a330b0164aa3cd07680454095e9e050a

See more details on using hashes here.

Provenance

The following attestation bundles were made for ycleptic-2.2.1.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.2.1-py3-none-any.whl.

File metadata

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

File hashes

Hashes for ycleptic-2.2.1-py3-none-any.whl
Algorithm Hash digest
SHA256 873d86de9f2226faf1693c785f923bb75336e9b1a3197979a3df6fa2a25807f2
MD5 92f703cc359cf8a241c2a3f6a8afb2e8
BLAKE2b-256 7ed65dea9fb5fd26c5b6333eb8516ed5a316fb7ec4edabdc10aacb382e89b449

See more details on using hashes here.

Provenance

The following attestation bundles were made for ycleptic-2.2.1-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

2.3.0

2 files

2.2.2

2 files

This release

2.2.1 This release

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