ycleptic 2.2.0__tar.gz → 2.2.2__tar.gz

{ycleptic-2.2.0 → ycleptic-2.2.2}/CHANGELOG.md

@@ -5,6 +5,23 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [2.2.2] - 2026-08-13
+
+### Added
+- Status badges (PyPI version, supported Python versions, CI, documentation, license) on the README and the documentation landing page
+
+### Fixed
+- Interactive `config-help` no longer ends with an uncaught traceback when stdin reaches EOF (piped or redirected input) or when the user presses Ctrl-C; either case now quits the session cleanly, exactly as if the user had typed `!`
+
+## [2.2.1] - 2026-07-21
+
+### Changed
+- Repositioned the README and documentation landing page to lead with Ycleptic's distinctive workflow — one YAML schema as a single source of truth for validation, generated documentation, and interactive help — with an honest "when to use it" comparison to pydantic, jsonschema, and Hydra
+
+### Fixed
+- `example_base.yaml` used `options:` for two attributes, but only `choices:` is actually validated; those keys are now `choices:` so the shipped example enforces its allowed values as documented
+- Documentation audit: corrected the allowed-values key from `options` to `choices` throughout; documented the previously-undocumented `case_sensitive` key and the `tuple` type; fixed the non-runnable `MyConfig` example snippets (`super().__init__(basefile, userfile=...)` and a missing `import os`); replaced stale "Directive" terminology left from the 2.0.3 rename; added a Quickstart page and a worked `docs:` example; fleshed out the `config-help` page with sample output; and fixed assorted typos
+
 ## [2.2.0] - 2026-07-21
 
 ### Added

ycleptic-2.2.2/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.5
+Name: ycleptic
+Version: 2.2.2
+Summary: A YAML-format configuration generator
+Project-URL: Source, https://github.com/cameronabrams/ycleptic
+Project-URL: Documentation, https://ycleptic.readthedocs.io/en/latest/
+Project-URL: Bug Tracker, https://github.com/cameronabrams/ycleptic/issues
+Author-email: Cameron F Abrams <cfa22@drexel.edu>
+License: MIT License
+        
+        Copyright (c) 2022 Cameron Abrams
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Requires-Dist: pyyaml>=6
+Provides-Extra: lint
+Requires-Dist: mypy; extra == 'lint'
+Requires-Dist: ruff==0.15.22; extra == 'lint'
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Ycleptic
+> Self-documenting YAML configuration for Python applications
+
+[![PyPI](https://img.shields.io/pypi/v/ycleptic)](https://pypi.org/project/ycleptic/)
+[![Python versions](https://img.shields.io/pypi/pyversions/ycleptic)](https://pypi.org/project/ycleptic/)
+[![CI](https://github.com/cameronabrams/ycleptic/actions/workflows/ci.yaml/badge.svg)](https://github.com/cameronabrams/ycleptic/actions/workflows/ci.yaml)
+[![Documentation Status](https://readthedocs.org/projects/ycleptic/badge/?version=latest)](https://ycleptic.readthedocs.io/en/latest/?badge=latest)
+[![License: MIT](https://img.shields.io/pypi/l/ycleptic)](https://github.com/cameronabrams/ycleptic/blob/main/LICENSE)
+
+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](https://docs.pydantic.dev/) or
+  [jsonschema](https://python-jsonschema.readthedocs.io/);
+- **composable, hierarchical config with overrides and interpolation** — reach
+  for [Hydra / OmegaConf](https://hydra.cc/).
+
+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:
+
+```yaml
+# 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):
+
+```python
+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:
+
+```bash
+yclept make-doc mypackage/data/base.yaml --root docs/source/config_ref
+```
+
+and your users can explore the configuration interactively:
+
+```bash
+yclept config-help mypackage/data/base.yaml
+```
+
+## Installation
+
+```bash
+pip install ycleptic
+```
+
+## Documentation
+
+Full documentation is at <https://ycleptic.readthedocs.io/en/latest/>.
+
+## Release History
+
+See [CHANGELOG.md](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/cameronabrams/)
+
+[https://github.com/AbramsGroup](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

ycleptic-2.2.2/README.md

@@ -0,0 +1,120 @@
+# Ycleptic
+> Self-documenting YAML configuration for Python applications
+
+[![PyPI](https://img.shields.io/pypi/v/ycleptic)](https://pypi.org/project/ycleptic/)
+[![Python versions](https://img.shields.io/pypi/pyversions/ycleptic)](https://pypi.org/project/ycleptic/)
+[![CI](https://github.com/cameronabrams/ycleptic/actions/workflows/ci.yaml/badge.svg)](https://github.com/cameronabrams/ycleptic/actions/workflows/ci.yaml)
+[![Documentation Status](https://readthedocs.org/projects/ycleptic/badge/?version=latest)](https://ycleptic.readthedocs.io/en/latest/?badge=latest)
+[![License: MIT](https://img.shields.io/pypi/l/ycleptic)](https://github.com/cameronabrams/ycleptic/blob/main/LICENSE)
+
+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](https://docs.pydantic.dev/) or
+  [jsonschema](https://python-jsonschema.readthedocs.io/);
+- **composable, hierarchical config with overrides and interpolation** — reach
+  for [Hydra / OmegaConf](https://hydra.cc/).
+
+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:
+
+```yaml
+# 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):
+
+```python
+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:
+
+```bash
+yclept make-doc mypackage/data/base.yaml --root docs/source/config_ref
+```
+
+and your users can explore the configuration interactively:
+
+```bash
+yclept config-help mypackage/data/base.yaml
+```
+
+## Installation
+
+```bash
+pip install ycleptic
+```
+
+## Documentation
+
+Full documentation is at <https://ycleptic.readthedocs.io/en/latest/>.
+
+## Release History
+
+See [CHANGELOG.md](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/cameronabrams/)
+
+[https://github.com/AbramsGroup](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

ycleptic-2.2.2/docs/source/index.rst

@@ -0,0 +1,46 @@
+ycleptic
+========
+
+|pypi| |pyversions| |ci| |docs| |license|
+
+.. |pypi| image:: https://img.shields.io/pypi/v/ycleptic
+   :target: https://pypi.org/project/ycleptic/
+   :alt: PyPI version
+.. |pyversions| image:: https://img.shields.io/pypi/pyversions/ycleptic
+   :target: https://pypi.org/project/ycleptic/
+   :alt: Supported Python versions
+.. |ci| image:: https://github.com/cameronabrams/ycleptic/actions/workflows/ci.yaml/badge.svg
+   :target: https://github.com/cameronabrams/ycleptic/actions/workflows/ci.yaml
+   :alt: CI status
+.. |docs| image:: https://readthedocs.org/projects/ycleptic/badge/?version=latest
+   :target: https://ycleptic.readthedocs.io/en/latest/?badge=latest
+   :alt: Documentation status
+.. |license| image:: https://img.shields.io/pypi/l/ycleptic
+   :target: https://github.com/cameronabrams/ycleptic/blob/main/LICENSE
+   :alt: License: MIT
+
+**Ycleptic** (ee-KLEP-tic) turns a single, structured YAML file into a self-documenting configuration system for your Python application.  From one schema file you get three things at once: validation of a user's config (with defaults, allowed value ``choices``, and required parameters), an automatically generated RST/Sphinx documentation tree, and an interactive help explorer for your users.  Because the schema is data rather than Python code, editing that one file keeps validation, documentation, and help in lockstep.
+
+Ycleptic is intentionally lightweight on validation and focuses on the *spec-as-documentation* workflow — a good fit for scientific and command-line applications whose users are domain experts.  If you need heavyweight validation and coercion, `pydantic <https://docs.pydantic.dev/>`_ or `jsonschema <https://python-jsonschema.readthedocs.io/>`_ are better suited; for composable, hierarchical config, see `Hydra <https://hydra.cc/>`_.
+
+.. note::
+
+   Ycleptic is under active development.
+
+.. note:: 
+
+   Ycleptic is used in the `pestifer <https://pypi.org/project/pestifer/>`_ package.
+
+Contents
+--------
+
+.. toctree::
+   :maxdepth: 1
+
+   about
+   installation
+   usage
+   API <api/API>
+   roadmap
+   changelog
+

{ycleptic-2.2.0 → ycleptic-2.2.2}/docs/source/usage/class.rst

@@ -34,13 +34,14 @@ You then might like to create a "config" class for your package that inherits :c
 
 .. code-block:: python
 
+  import os
   from ycleptic.yclept import Yclept
   from mypackage import data # to get the path to your package data; there are other ways to do this
 
   class MyConfig(Yclept):
     def __init__(self, userconfigfile=''):
         basefile=os.path.join(os.path.dirname(data.__file__),"base.yaml")  # your app's base config
-        super().__init__(data.basefile,userconfigfile=userconfigfile)
+        super().__init__(basefile, userfile=userconfigfile)
 
 
 Here, ``data`` is just a directory where you store your package data (``rootdir/mypackage/data``, in the example), and you can put ``base.yaml`` in that directory as the base configuration description.  Essentially, it is a description of **what** can be configured by a **user's** configuration file when **they** run your app.  Now, inside your app source, if you want to read in the user's configuration file (like if its name was passed in as a command-line argument), you would instantiate a member of the ``MyConfig`` class:

{ycleptic-2.2.0 → ycleptic-2.2.2}/docs/source/usage/interactive_help.rst

@@ -3,19 +3,20 @@
 Interactive Help
 ===================
 
-The ``Yclept`` class has a method called ``console_help()`` that is meant to provides interactive help to a package user trying to develop their own config file that conform's to your package's base config.  
+The ``Yclept`` class has a method called ``console_help()`` that is meant to provide interactive help to a package user trying to develop their own config file that conforms to your package's base config.
 
 Suppose this is the content of ``config.py``:
 
 .. code-block:: python
 
+  import os
   from ycleptic.yclept import Yclept
   from mypackage import data
 
   class MyConfig(Yclept):
     def __init__(self, userconfigfile=''):
         basefile=os.path.join(os.path.dirname(data.__file__),"base.yaml")
-        super().__init__(data.basefile,userconfigfile=userconfigfile)
+        super().__init__(basefile, userfile=userconfigfile)
    
 
 Here is an example of how the interactive help works:
@@ -36,7 +37,7 @@ This reflects the fact that the three top-level attributes available are called
 
 .. code-block:: console
 
-    >>> Y.console_help([],interactive_prompt='help: ')
+    >>> c.console_help([],interactive_prompt='help: ')
         attribute_1 ->
         attribute_2 ->
         attribute_3 ->
@@ -45,7 +46,7 @@ This reflects the fact that the three top-level attributes available are called
     help: attribute_1
 
     attribute_1:
-        This is a description of Directive 1
+        This is a description of Attribute 1
 
     base|attribute_1
         attribute_1_1

ycleptic-2.2.2/docs/source/usage/quickstart.rst

@@ -0,0 +1,72 @@
+.. _usage_quickstart:
+
+Quickstart
+==========
+
+This is the smallest useful Ycleptic setup: define a base config, load a user
+config against it, and generate documentation — all from one schema file.
+
+1. Write a base config
+-----------------------------
+
+The base config is a YAML file describing what your users may configure.  Ship
+it as package data, e.g. ``mypackage/data/base.yaml``:
+
+.. code-block:: 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
+
+2. Load a user config
+-----------------------------
+
+Read the base config together with a user's config through
+:class:`ycleptic.yclept.Yclept`.  Omitted values are filled in from their
+declared defaults; invalid values raise :class:`ycleptic.YclepticError`:
+
+.. code-block:: python
+
+  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}')
+
+  print(config['user']['temperature'])   # 300.0 if the user omitted it
+
+If ``user.yaml`` sets only the integrator:
+
+.. code-block:: yaml
+
+  integrator: langevin
+
+then ``config['user']`` becomes ``{'integrator': 'langevin', 'temperature':
+300.0}`` — the default temperature is supplied automatically.
+
+3. Generate documentation and explore
+--------------------------------------------
+
+From the *same* base config you can generate a Sphinx reference tree:
+
+.. code-block:: console
+
+  $ yclept make-doc mypackage/data/base.yaml --root docs/source/config_ref
+
+and let your users explore the configuration interactively:
+
+.. code-block:: console
+
+  $ yclept config-help mypackage/data/base.yaml
+
+The rest of this guide covers each piece in detail: :ref:`usage_the_base_config`,
+:ref:`usage_the_user_config`, :ref:`usage_interactive_help`, and
+:ref:`usage_yclept_makedoc`.

{ycleptic-2.2.0 → ycleptic-2.2.2}/docs/source/usage/resource_file.rst

@@ -5,22 +5,22 @@ Resource File
 
 You may want users of your application to be able to set their own global default values for attributes, overwriting defaults you define in your application's base configuration.  ``Yclept`` supports reading a secondary resource file (e.g., ``~/.your_app_name.rc``) in which users can specify attributes that replace or add to the list of attributes in your application's base configuration.
 
-For example, continuing with the base configuration defined above, suppose a user of your application has the file ``~/.your_app_name.rc`` with these contents:
+For example, continuing with the base configuration from :ref:`usage_the_base_config`, suppose a user of your application has the file ``~/.your_app_name.rc`` with these contents:
 
 .. code-block:: yaml
 
   attributes:
     - name: attribute_2
       type: list
-      text: Directive 2 is interpretable as an ordered list of attributes
+      text: Attribute 2 is interpretable as an ordered list of attributes
       attributes:
         - name: attribute_2a
           type: dict
-          text: Directive 2a is one possible attribute in a user's list
+          text: Attribute 2a is one possible attribute in a user's list
           attributes:
             - name: d2a_val2
               type: int
-              text: An int for Value 2 of Directive 2a
+              text: An int for Value 2 of Attribute 2a
               default: 7 # user has changed this in their resource file
 
 The presence of this file indicates the user would like the default value of attribute ``d2a_val2`` under attribute ``attribute_2a`` of base attribute ``attribute_2`` to be 7 instead of 6.

{ycleptic-2.2.0 → ycleptic-2.2.2}/docs/source/usage/the_base_config.rst

@@ -22,7 +22,7 @@ The heart of ``ycleptic`` is the base configuration file, which the app develope
         - name: attribute_1_2
           type: str
           text: This is a description of Attribute 1.2
-          options: [ValA, ValB]
+          choices: [valA, valB]
     - name: attribute_2
       type: list
       text: Attribute 2 is interpretable as an ordered list of attributes
@@ -101,7 +101,7 @@ The heart of ``ycleptic`` is the base configuration file, which the app develope
                     - name: flipaxis
                       type: str
                       text: Axis around which flip is performed
-                      options: ['x','y','z']
+                      choices: ['x','y','z']
                 - name: d322b
                   type: dict
                   text: Subattribute D 3.2.2b saves the result
@@ -114,7 +114,7 @@ The heart of ``ycleptic`` is the base configuration file, which the app develope
 
 The base config must open with the single identifier ``attributes``, under which is a list of one or more top-level attributes.  Every attribute must have a declared type, and attributes can be nested.
 
-``type`` can be one of ``int``, ``float``, ``str``, ``bool``, ``list``, or ``dict``.  The data content in a attribute is of type ``type`` unless two conditions are met:
+``type`` can be one of ``int``, ``float``, ``str``, ``bool``, ``tuple``, ``list``, or ``dict``.  The data content in an attribute is of type ``type`` unless two conditions are met:
 
 1. ``type`` is either ``list`` or ``dict``; and
 2. the keyword ``attributes`` is present.
@@ -123,9 +123,41 @@ In this case, there are subattributes.  If the ``type`` was ``dict``, then the s
 
 ``text`` is just meant for helpful text describing the attribute, and it can be completely free-form as long as it is on one line or blocked multiline using ``|``.
 
-There are four other keys that a attribute may have:
+There are several other keys an attribute may have:
 
-1. ``default``: as you might expect, this are default values to assign to the attribute if the user "declares" the attribute but does not provide it any values.
-2. ``required``:  a boolean.  If False, that means no defaults are assigned; if a user declares this attribute without providing values, an error occurs, but a user need not declare this attribute at all.  If True, the attribute must be declared (and if it is nested, all the antecedant attributes must also be declared).
-3. ``options``: a list of allowed values; if the user declares this attribute with a value not in this list, an error occurs.
-4. ``docs``: this is a subattribute that can have ``title``, ``text``, and ``example`` keys.  ``title`` and ``text`` are strings used in automatic documentation generation using ``yclept make-doc``.  ``example`` is a YAML-format example of how to use the attribute in a config file.  This is used in the documentation generation as well.
+1. ``default``: the default value (or values) assigned to the attribute when the user declares it but provides no value.
+2. ``required``: a boolean.  If ``True``, the attribute must be declared (and if it is nested, all its antecedent attributes must be declared too).  If ``False``, no defaults are assigned: the user need not declare the attribute at all, but declaring it without providing a value is an error.
+3. ``choices``: a list of allowed values; if the user gives a value that is not in the list, an error occurs.  For ``str`` attributes the comparison honors ``case_sensitive`` (below).
+4. ``case_sensitive``: for ``str`` attributes only; a boolean that defaults to ``True``.  When ``False``, the user's value is matched against ``choices`` case-insensitively and stored in casefolded (lower-case) form.
+5. ``docs``: a block that enriches the output of ``yclept make-doc``.  It may contain ``title`` and ``text`` strings and a YAML-format ``example`` showing the attribute in use.  See :ref:`base_config_docs_key` below.
+
+.. _base_config_docs_key:
+
+Enriching generated documentation with ``docs``
+-------------------------------------------------
+
+The ``text`` key gives every attribute a one-line description that appears in
+interactive help and generated documentation.  When you want richer, prose
+documentation for an attribute — the kind you would write into a reference
+manual — add a ``docs`` block.  It is used only by ``yclept make-doc`` and is
+ignored during configuration validation:
+
+.. code-block:: yaml
+
+  - name: integrator
+    type: str
+    text: Integration scheme to use
+    choices: [verlet, langevin]
+    default: verlet
+    docs:
+      title: Integration scheme
+      text: |
+        Selects the time-integration algorithm.  ``verlet`` is symplectic and
+        conserves energy well; ``langevin`` couples the system to a heat bath
+        and is appropriate for constant-temperature runs.
+      example:
+        integrator: langevin
+
+``title`` and ``text`` supply a heading and prose for the attribute's generated
+page, and ``example`` is rendered as a YAML code block showing the attribute in
+use.  See :ref:`usage_yclept_makedoc` for how the tree is generated.

ycleptic-2.2.2/docs/source/usage/yclept_config-help.rst

@@ -0,0 +1,41 @@
+.. _usage_yclept_config_help:
+
+``yclept config-help``
+========================
+
+The command-line tool ``yclept config-help <base.yaml>`` lets you use the interactive help feature detailed in :ref:`usage_interactive_help` to explore a base configuration file directly, without writing any code.  For example, if you have a base configuration file called ``base.yaml``, you can run:
+
+.. code-block:: console
+
+   $ yclept config-help base.yaml
+
+which drops you into the interactive explorer:
+
+.. code-block:: console
+
+   $ yclept config-help base.yaml
+       attribute_1 ->
+       attribute_2 ->
+       attribute_3 ->
+       .. up
+       ! quit
+   help: attribute_2
+
+   attribute_2:
+       Attribute 2 is interpretable as an ordered list of attributes
+
+   base|attribute_2
+       attribute_2a ->
+       attribute_2b ->
+       .. up
+       ! quit
+   help: !
+
+At each prompt, type an attribute name to drill into it, ``..`` to go back up a
+level, and ``!`` to quit.  A trailing ``->`` marks an attribute that has
+subattributes.  You can also pass a space-separated attribute path on the
+command line to jump straight to a node, for example:
+
+.. code-block:: console
+
+   $ yclept config-help base.yaml attribute_2 attribute_2a

{ycleptic-2.2.0 → ycleptic-2.2.2}/docs/source/usage/yclept_makedoc.rst

@@ -77,7 +77,7 @@ Each generated RST file ends with a footer whose appearance is controlled by
 
       ----
 
-      This page was automatically generated by **ycleptic** v2.0.3 on 2025-09-04.
+      This page was automatically generated by **ycleptic** vX.Y.Z on YYYY-MM-DD.
 
 ``comment``
    An RST comment — present in the source but invisible in the rendered output.

{ycleptic-2.2.0 → ycleptic-2.2.2}/docs/source/usage.rst

@@ -3,9 +3,10 @@ Usage
 
 ``Ycleptic`` primarily exposes the :class:`ycleptic.yclept.Yclept` class to inherit in your own applications.  It also has a command-line interface with two subcommands: ``yclept config-help`` and ``yclept make-doc``.  The former provides interactive help for the configuration file, and the latter generates documentation from the base configuration file.
 
-.. toctree:: 
+.. toctree::
    :maxdepth: 1
 
+   usage/quickstart
    usage/class
    usage/the_base_config
    usage/the_user_config

{ycleptic-2.2.0 → ycleptic-2.2.2}/pyproject.toml

@@ -3,7 +3,7 @@ requires = ["hatchling"]
 build-backend = "hatchling.build"
 [project]
 name = "ycleptic"
-version = "2.2.0"
+version = "2.2.2"
 authors = [
   { name="Cameron F Abrams", email="cfa22@drexel.edu" },
 ]

{ycleptic-2.2.0 → ycleptic-2.2.2}/tests/test_set.py

@@ -270,6 +270,42 @@ base|attribute_2->attribute_2a
         with open('console-out.txt', 'r') as f:
             self.assertEqual(f.read(), ref_str)
 
+    def test_console_help_eof_quits_cleanly(self):
+        """EOF on stdin ends an interactive help session as if the user typed '!'."""
+        from unittest.mock import patch
+
+        Y = Yclept(BFILE)
+        with open('console-out.txt', 'w') as f:
+            with redirect_stdout(f):
+                with patch('builtins.input', side_effect=EOFError):
+                    Y.console_help([], interactive_prompt='help: ')
+        with open('console-out.txt', 'r') as f:
+            self.assertIn('! quit', f.read())
+
+    def test_console_help_eof_after_bad_choice_quits_cleanly(self):
+        """EOF also ends the session from the re-prompt after an unrecognized choice."""
+        from unittest.mock import patch
+
+        Y = Yclept(BFILE)
+        with open('console-out.txt', 'w') as f:
+            with redirect_stdout(f):
+                with patch('builtins.input', side_effect=['bogus', EOFError]):
+                    Y.console_help([], interactive_prompt='help: ')
+        with open('console-out.txt', 'r') as f:
+            self.assertIn('bogus not recognized.', f.read())
+
+    def test_console_help_keyboard_interrupt_quits_cleanly(self):
+        """Ctrl-C at the prompt ends the session cleanly rather than raising."""
+        from unittest.mock import patch
+
+        Y = Yclept(BFILE)
+        with open('console-out.txt', 'w') as f:
+            with redirect_stdout(f):
+                with patch('builtins.input', side_effect=KeyboardInterrupt):
+                    Y.console_help([], interactive_prompt='help: ')
+        with open('console-out.txt', 'r') as f:
+            self.assertIn('! quit', f.read())
+
     def test_makedoc(self):
         Y = Yclept(BFILE)
         Y.make_doctree('ydoc')
@@ -328,6 +364,15 @@ Subattributes:
         Y = Yclept(BFILE, userfile='example1.yaml')
         self.assertEqual(Y['user']['attribute_5'], 'b')
 
+    def test_choices_case_sensitive_invalid(self):
+        """A value outside a case-sensitive attribute's choices is rejected."""
+        # attribute_1_2 has choices [valA, valB] and is case-sensitive by default,
+        # so 'ValA' (wrong case) must be rejected.
+        with open('example1.yaml', 'w') as f:
+            f.write('attribute_1:\n  attribute_1_2: ValA\n')
+        with self.assertRaises(YclepticError):
+            Yclept(BFILE, userfile='example1.yaml')
+
     def test_choices_invalid(self):
         """attribute_5 rejects a value not in its choices list."""
         with open('example1.yaml', 'w') as f:

{ycleptic-2.2.0 → ycleptic-2.2.2}/ycleptic/resources/example_base.yaml

@@ -26,7 +26,7 @@ attributes:
       - name: attribute_1_2
         type: str
         text: This is a description of Attribute 1.2
-        options: [ValA, ValB]
+        choices: [valA, valB]
   - name: attribute_2
     type: list
     text: Attribute 2 is interpretable as an ordered list of attributes
@@ -105,7 +105,7 @@ attributes:
                   - name: flipaxis
                     type: str
                     text: Axis around which flip is performed
-                    options: ['x','y','z']
+                    choices: ['x','y','z']
               - name: d322b
                 type: dict
                 text: Subattribute D 3.2.2b saves the result

{ycleptic-2.2.0 → ycleptic-2.2.2}/ycleptic/yclept.py

@@ -201,23 +201,32 @@ class Yclept(UserDict):
                 c = ''
             H.write_func(f'    {m}{c}{a}')
 
+    def _prompt_choice(self):
+        H: Namespace = self.H
+        choice = '!'
+        if H.interactive_prompt != '':
+            try:
+                choice = input(H.interactive_prompt)
+            except (EOFError, KeyboardInterrupt):
+                # no more input, or the user interrupted; quit as though
+                # the user had typed '!'
+                H.write_func('')
+                choice = '!'
+        return choice
+
     def _get_help_choice(self, init_list: list[str]):
         H: Namespace = self.H
         if len(init_list) > 0:
             choice = init_list.pop()
         else:
-            choice = '!'
-            if H.interactive_prompt != '':
-                choice = input(H.interactive_prompt)
+            choice = self._prompt_choice()
         while choice == '' or choice not in [x['name'] for x in H.base] + ['..', '!']:
             if choice != '':
                 H.write_func(f'{choice} not recognized.')
             if len(init_list) > 0:
                 choice = init_list.pop()
             else:
-                choice = '!'
-                if H.interactive_prompt != '':
-                    choice = input(H.interactive_prompt)
+                choice = self._prompt_choice()
         return choice
 
     def _help(self):

ycleptic-2.2.0/PKG-INFO

@@ -1,88 +0,0 @@
-Metadata-Version: 2.4
-Name: ycleptic
-Version: 2.2.0
-Summary: A YAML-format configuration generator
-Project-URL: Source, https://github.com/cameronabrams/ycleptic
-Project-URL: Documentation, https://ycleptic.readthedocs.io/en/latest/
-Project-URL: Bug Tracker, https://github.com/cameronabrams/ycleptic/issues
-Author-email: Cameron F Abrams <cfa22@drexel.edu>
-License: MIT License
-        
-        Copyright (c) 2022 Cameron Abrams
-        
-        Permission is hereby granted, free of charge, to any person obtaining a copy
-        of this software and associated documentation files (the "Software"), to deal
-        in the Software without restriction, including without limitation the rights
-        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-        copies of the Software, and to permit persons to whom the Software is
-        furnished to do so, subject to the following conditions:
-        
-        The above copyright notice and this permission notice shall be included in all
-        copies or substantial portions of the Software.
-        
-        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-        SOFTWARE.
-License-File: LICENSE
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Requires-Python: >=3.9
-Requires-Dist: pyyaml>=6
-Provides-Extra: lint
-Requires-Dist: mypy; extra == 'lint'
-Requires-Dist: ruff==0.15.22; extra == 'lint'
-Provides-Extra: test
-Requires-Dist: pytest; extra == 'test'
-Description-Content-Type: text/markdown
-
-# Ycleptic
-> YAML configuration generator
-
-YAML is a popular markup language for input files, with its easy syntax and clear
-mapping to lists and dicts.  Ycleptic allows a developer to specify all keys, datatypes,
-default values, choice restrictions, and other features of YAML-format input 
-files for use in their own apps. This makes the specification of input file syntax on top 
-of YAML for any particular application a bit easier than just using pure YAML.  In addition,
-ycleptic can also automatically build the RST/Sphinx doctree for your app's configuration
-file.
-
-## Installation
-
-```bash
-pip install ycleptic
-```
-
-Once installed, the developer has access to the ``Yclept`` class.
-
-## Release History
-
-See [CHANGELOG.md](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/cameronabrams/)
-
-[https://github.com/AbramsGroup](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
-

ycleptic-2.2.0/README.md

@@ -1,41 +0,0 @@
-# Ycleptic
-> YAML configuration generator
-
-YAML is a popular markup language for input files, with its easy syntax and clear
-mapping to lists and dicts.  Ycleptic allows a developer to specify all keys, datatypes,
-default values, choice restrictions, and other features of YAML-format input 
-files for use in their own apps. This makes the specification of input file syntax on top 
-of YAML for any particular application a bit easier than just using pure YAML.  In addition,
-ycleptic can also automatically build the RST/Sphinx doctree for your app's configuration
-file.
-
-## Installation
-
-```bash
-pip install ycleptic
-```
-
-Once installed, the developer has access to the ``Yclept`` class.
-
-## Release History
-
-See [CHANGELOG.md](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/cameronabrams/)
-
-[https://github.com/AbramsGroup](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
-

ycleptic-2.2.0/docs/source/changelog.md

@@ -1,5 +0,0 @@
-# Changelog
-
-```{include} ../../CHANGELOG.md
-:heading-offset: 1
-```

ycleptic-2.2.0/docs/source/index.rst

@@ -1,26 +0,0 @@
-ycleptic
-========
-
-**Ycleptic** (ee-KLEP-tic) is a Python tool for facilitating the definition of YAML-format input files.  It allows for specification of default values and value choices.  It allows for fully nested dictionary/list structures for detailed input file organization.
-
-.. note::
-
-   Ycleptic is under active development.
-
-.. note:: 
-
-   Ycleptic is used in the `pestifer <https://pypi.org/project/pestifer/>`_ package.
-
-Contents
---------
-
-.. toctree::
-   :maxdepth: 1
-
-   about
-   installation
-   usage
-   API <api/API>
-   roadmap
-   changelog
-

ycleptic-2.2.0/docs/source/usage/yclept_config-help.rst

@@ -1,10 +0,0 @@
-.. _usage_yclept_config_help:
-
-``yclept config-help``
-========================
-
-The command-line tool `yclept config-help <base.yaml>` allow you to use the interactive help feature detailed in :ref:`usage_interactive_help` to explore a base configuration file.  For example, if you have a base configuration file called `base.yaml`, you can run the following command:
-
-.. code-block:: console
-
-   $ yclept config-help base.yaml