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:
- 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. - Generated documentation —
yclept make-docbuilds an RST/Sphinx documentation tree for your config directly from the schema. - Interactive help —
yclept config-helplets 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
- Fork it (https://github.com/cameronabrams/ycleptic/fork)
- Create your feature branch (
git checkout -b feature/fooBar) - Commit your changes (
git commit -am 'Add some fooBar') - Push to the branch (
git push origin feature/fooBar) - Create a new Pull Request
1 maintainer
Metadata
1 maintainer
Release files for ycleptic 2.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| ycleptic-2.4.0.tar.gz | 58.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| ycleptic-2.4.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 85.5 kB
Release files / ycleptic-2.4.0.tar.gz
| Download URL | ycleptic-2.4.0.tar.gz |
|---|---|
| Size | 58.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8def01e282b70f67d3f44660fcda3a8d5772f99ca93a7b8378da1685009879bd
|
|
BLAKE2b-256 checksum How to use checksums |
30dd36cb7048b833ce102182bb9577b657c33c1abab8188ff71b62ec0bd4ebe5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 8, 2026.
Transparency logRelease files / ycleptic-2.4.0-py3-none-any.whl
| Download URL | ycleptic-2.4.0-py3-none-any.whl |
|---|---|
| Size | 27.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7bfd123a4167286cc45353f0d233895e9326a19ea1a57aae99c8172d635e9776
|
|
BLAKE2b-256 checksum How to use checksums |
e802779587629eb0637541274bcdf0f9db53c9fe55386d0c1f3c4ee856276d3e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 8, 2026.
Transparency log
