Skip to main content

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

Metadata

Release files for ycleptic 2.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ycleptic 2.5.0
File Size Uploaded Provenance Actions
ycleptic-2.5.0.tar.gz 510.0 kB With provenance Details for ycleptic-2.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ycleptic 2.5.0
File Interpreter ABI Platform Actions
ycleptic-2.5.0-py3-none-any.whl Python 3 none any Details for ycleptic-2.5.0-py3-none-any.whl

Total release size: 539.9 kB

Release files / ycleptic-2.5.0.tar.gz

Download URL ycleptic-2.5.0.tar.gz
Size 510.0 kB
Tags Source
SHA-256 checksum
How to use checksums
be6757675e38923f38f7f15eae74e68d3b244bd01247c50cb8cbc45f99aeedc9
BLAKE2b-256 checksum
How to use checksums
9e9c5f76ec6a8f4b1aad0cf8a2d063d23c306cf133e9aa44838ab92fb9d8fdc7
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 Oct 19, 2026.

Transparency log

Release files / ycleptic-2.5.0-py3-none-any.whl

Download URL ycleptic-2.5.0-py3-none-any.whl
Size 29.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d67719b6092eadb64bc71822ed75edabeff000abe248f5ff28b5cedf6524e494
BLAKE2b-256 checksum
How to use checksums
a0602501260795400a37f503875bc975747acbea4c2c2ff3ae6646c9a5ef1dbd
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 Oct 19, 2026.

Transparency log

Security for ycleptic 2.5.0

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ycleptic-2.5.0.tar.gz

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 Oct 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.5.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page