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:
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 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.2.2.tar.gz (38.4 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.2-py3-none-any.whl (20.1 kB view details)

Uploaded Python 3

File details

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

File metadata

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

File hashes

Hashes for ycleptic-2.2.2.tar.gz
Algorithm Hash digest
SHA256 8bcd7d027f593551ec1dae3428e514a7cd627bec7d4f531ea05e480d3fb9c63d
MD5 498254940cf32c66fbd0748b80de186b
BLAKE2b-256 d6f4ac688581eafd413b51ef0f9ae1715920d39c6937e2a543cfacff6ff9ac10

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: ycleptic-2.2.2-py3-none-any.whl
  • Upload date:
  • Size: 20.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.2.2-py3-none-any.whl
Algorithm Hash digest
SHA256 92ecf7e63a9a6e29f2fbcbd5b50683c8e9e45a46d92b3a4aee46001e7902154b
MD5 c5203d3d32a819e21f8e3ad062c7dcd7
BLAKE2b-256 c256d3fe8fa598c85d519ab38da879a6fb793333aa302e2040d6adbf031b9887

See more details on using hashes here.

Provenance

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

This release

2.2.2 This release

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