ycleptic 2.2.2__tar.gz → 2.3.0__tar.gz

{ycleptic-2.2.2 → ycleptic-2.3.0}/.gitignore

@@ -85,6 +85,7 @@ tests/test_set/console-out.txt
 tests/test_set/ydoc.rst
 tests/test_set/ydoc/
 tests/test_set/rcfile.yaml
+tests/test_set/spec-check-base.yaml
 
 # PyBuilder
 target/

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

@@ -5,6 +5,17 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [2.3.0] - 2026-08-13
+
+### Added
+- Base config specifications are now checked when they are loaded, and any declaration ycleptic ignores is reported: a key outside the recognized set (`options:` where `choices:` was meant), an unrecognized `type:` name (`string` instead of `str`), an attribute with no declared type, and `choices` on a non-`str` attribute, which is not enforced. Such a declaration silently does nothing, so an attribute its author believes is constrained may in fact accept any value. Findings are issued as a `YclepticSpecWarning` and the config still loads; `Yclept(..., strict_spec=True)` raises `YclepticError` instead
+- `yclept check-spec <base.yaml>` reports the same findings from the command line and exits nonzero when any are found, so it can gate a CI run
+- `ycleptic.speccheck.check_base_spec`, which returns the findings as a list of strings
+
+### Fixed
+- `yclept make-doc` now renders an attribute's `choices` as "Allowed values" in the generated documentation. Interactive help has always shown them, so generated docs and interactive help disagreed about what the schema allowed
+- An attribute with no declared `type` now reports a clean error naming the attribute, instead of raising `KeyError: 'type'`
+
 ## [2.2.2] - 2026-08-13
 
 ### Added

{ycleptic-2.2.2 → ycleptic-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ycleptic
-Version: 2.2.2
+Version: 2.3.0
 Summary: A YAML-format configuration generator
 Project-URL: Source, https://github.com/cameronabrams/ycleptic
 Project-URL: Documentation, https://ycleptic.readthedocs.io/en/latest/

{ycleptic-2.2.2 → ycleptic-2.3.0}/docs/source/api/ycleptic.rst

@@ -24,6 +24,7 @@ Submodules
    ycleptic.dictthings
    ycleptic.errors
    ycleptic.makedoc
+   ycleptic.speccheck
    ycleptic.stringthings
    ycleptic.walkers
    ycleptic.yclept

ycleptic-2.3.0/docs/source/api/ycleptic.speccheck.rst

@@ -0,0 +1,7 @@
+ycleptic.speccheck module
+=========================
+
+.. automodule:: ycleptic.speccheck
+   :members:
+   :show-inheritance:
+   :undoc-members:

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

@@ -127,10 +127,24 @@ There are several other keys an attribute may have:
 
 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).
+3. ``choices``: a list of allowed values; if the user gives a value that is not in the list, an error occurs.  This is currently enforced for ``str`` attributes only, and the comparison honors ``case_sensitive`` (below); on an attribute of any other type the list has no effect.  The allowed values appear in interactive help and in the output of ``yclept make-doc``.
 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.
 
+.. warning::
+
+   A base config is data, and ycleptic reads only the keys listed above.  Any
+   other key is discarded without comment, so a misspelling leaves you with a
+   declaration that does nothing --- writing ``options:`` instead of
+   ``choices:`` yields an attribute that looks constrained but accepts any
+   value.  The same is true of the type names: ``type: string`` is not
+   ``type: str``, and an attribute with an unrecognized type is left entirely
+   unvalidated, its ``choices`` unenforced and its ``default`` never applied.
+
+   Constructing a :class:`~ycleptic.yclept.Yclept` reports these as a
+   :class:`~ycleptic.errors.YclepticSpecWarning`, and ``yclept check-spec``
+   reports them from the command line.  See :ref:`usage_yclept_check_spec`.
+
 .. _base_config_docs_key:
 
 Enriching generated documentation with ``docs``

ycleptic-2.3.0/docs/source/usage/yclept_check-spec.rst

@@ -0,0 +1,72 @@
+.. _usage_yclept_check_spec:
+
+``yclept check-spec``
+=====================
+
+A base config is data, and ycleptic reads only the keys it recognizes.  A
+misspelled key or type name is therefore discarded without comment, leaving you
+with a declaration that quietly does nothing.  The classic case is writing
+``options:`` where ycleptic expects ``choices:``: the attribute looks
+constrained, but every value is accepted.
+
+``yclept check-spec`` reads a base config file and reports every such
+declaration:
+
+.. code-block:: console
+
+   $ yclept check-spec base.yaml
+   base config base.yaml has 3 declarations ycleptic does not act on:
+     - attribute 'fetch->source': unrecognized key 'options' (did you mean 'choices'?); it is ignored
+     - attribute 'fetch->format': unrecognized type 'string' (did you mean 'str'?); the attribute is left unvalidated
+     - attribute 'run->nsteps': 'choices' is only enforced on 'str' attributes, and this one is 'int'; the allowed values are not applied
+
+It exits ``0`` when the spec is clean and ``1`` when anything is reported, so it
+can gate a CI run:
+
+.. code-block:: yaml
+
+   - name: Check the base config spec
+     run: yclept check-spec mypackage/data/base.yaml
+
+What it looks for
+-----------------
+
+1. Keys in an attribute node outside the recognized set (``name``, ``type``,
+   ``text``, ``default``, ``required``, ``choices``, ``case_sensitive``,
+   ``attributes``, ``docs``), and keys in a ``docs`` block outside ``title``,
+   ``text``, and ``example``.
+2. ``type`` values outside ``str``, ``int``, ``float``, ``bool``, ``tuple``,
+   ``list``, and ``dict``.  An unrecognized type name matches no branch of the
+   validator, so the attribute gets no handling at all --- including its
+   ``choices``, even when ``choices`` is spelled correctly, and including its
+   ``default``, which is never applied.
+3. Attributes with no ``type`` at all.
+4. ``choices`` on an attribute whose type is not ``str``.  Allowed values are
+   currently enforced only for strings, so elsewhere the list has no effect.
+
+Where a suggestion is obvious, it is offered: ``options`` for ``choices``,
+``string`` for ``str``, and so on.
+
+Checking from Python
+--------------------
+
+The same checks run whenever a :class:`~ycleptic.yclept.Yclept` is constructed.
+By default anything found is reported as a
+:class:`~ycleptic.errors.YclepticSpecWarning` and the config still loads, so an
+existing schema keeps working while you clean it up:
+
+.. code-block:: python
+
+   Y = Yclept('base.yaml', userfile='user.yaml')
+   # YclepticSpecWarning: base config base.yaml has 1 declaration ycleptic does not act on:
+   #   - attribute 'fetch->source': unrecognized key 'options' (did you mean 'choices'?); it is ignored
+
+Pass ``strict_spec=True`` to make it an error instead:
+
+.. code-block:: python
+
+   Y = Yclept('base.yaml', userfile='user.yaml', strict_spec=True)
+   # raises YclepticError
+
+:func:`ycleptic.speccheck.check_base_spec` returns the same findings as a list
+of strings if you would rather handle them yourself.

ycleptic-2.3.0/docs/source/usage.rst

@@ -0,0 +1,17 @@
+Usage
+=====
+
+``Ycleptic`` primarily exposes the :class:`ycleptic.yclept.Yclept` class to inherit in your own applications.  It also has a command-line interface with three subcommands: ``yclept config-help`` provides interactive help for the configuration file, ``yclept make-doc`` generates documentation from the base configuration file, and ``yclept check-spec`` reports declarations in a base configuration file that ycleptic ignores.
+
+.. toctree::
+   :maxdepth: 1
+
+   usage/quickstart
+   usage/class
+   usage/the_base_config
+   usage/the_user_config
+   usage/interactive_help
+   usage/resource_file
+   usage/yclept_config-help
+   usage/yclept_makedoc
+   usage/yclept_check-spec

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

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

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

@@ -1,18 +1,56 @@
 import shutil
 import unittest
-from contextlib import redirect_stdout
+from contextlib import redirect_stdout, redirect_stderr
 import os
 import yaml
 
 from ycleptic.yclept import Yclept
 from ycleptic import resources
-from ycleptic import YclepticError
-from ycleptic.cli import config_help
+from ycleptic import YclepticError, YclepticSpecWarning
+from ycleptic.speccheck import check_base_spec
+from ycleptic.cli import config_help, check_spec
 from ycleptic.dictthings import special_update
 from ycleptic.stringthings import oxford, generate_footer, dict_to_rst_yaml_block
 
 BFILE = os.path.join(os.path.dirname(resources.__file__), 'example_base.yaml')
 
+# A base spec exercising every silent-typo trap the spec checker looks for.
+BAD_SPEC_YAML = """
+attributes:
+  - name: a_opts
+    type: str
+    text: uses options instead of choices
+    options: [red, green]
+    default: red
+  - name: a_string
+    type: string
+    text: uses type string instead of str
+    choices: [red, green]
+    default: red
+  - name: an_int
+    type: int
+    text: choices on a non-str attribute
+    choices: [1, 2, 3]
+    default: 1
+  - name: nested
+    type: dict
+    text: a nested block
+    attributes:
+      - name: deep
+        type: str
+        text: a misspelled key one level down
+        chioces: [red, green]
+        docs:
+          titel: a misspelled docs key
+  - name: untyped
+    text: no type declared at all
+"""
+
+# The one trap above that stops a load outright, so tests can drop it.
+UNTYPED_ATTRIBUTE = """  - name: untyped
+    text: no type declared at all
+"""
+
 EXAMPLE1_YAML = """
 attribute_2:
   - attribute_2b:
@@ -306,6 +344,112 @@ base|attribute_2->attribute_2a
         with open('console-out.txt', 'r') as f:
             self.assertIn('! quit', f.read())
 
+    # ------------------------------------------------------------------
+    # Base-spec validation
+    # ------------------------------------------------------------------
+
+    def test_shipped_example_base_spec_is_clean(self):
+        """The shipped example must not trip its own spec checker."""
+        with open(BFILE, 'r') as f:
+            base = yaml.safe_load(f)
+        self.assertEqual(check_base_spec(base), [])
+
+    def test_spec_check_flags_options_instead_of_choices(self):
+        """'options' is read by nothing, so a schema using it is unvalidated."""
+        base = yaml.safe_load(BAD_SPEC_YAML)
+        problems = check_base_spec(base)
+        opt = [p for p in problems if "unrecognized key 'options'" in p]
+        self.assertEqual(len(opt), 1)
+        self.assertIn("attribute 'a_opts'", opt[0])
+        self.assertIn("did you mean 'choices'?", opt[0])
+
+    def test_spec_check_flags_string_instead_of_str(self):
+        """'string' matches no branch, so the attribute gets no string handling."""
+        base = yaml.safe_load(BAD_SPEC_YAML)
+        problems = check_base_spec(base)
+        typ = [p for p in problems if "unrecognized type 'string'" in p]
+        self.assertEqual(len(typ), 1)
+        self.assertIn("attribute 'a_string'", typ[0])
+        self.assertIn("did you mean 'str'?", typ[0])
+
+    def test_spec_check_flags_choices_on_non_str(self):
+        """'choices' is enforced only on str attributes; elsewhere it is inert."""
+        base = yaml.safe_load(BAD_SPEC_YAML)
+        problems = check_base_spec(base)
+        ch = [p for p in problems if "'choices' is only enforced" in p]
+        self.assertEqual(len(ch), 1)
+        self.assertIn("attribute 'an_int'", ch[0])
+
+    def test_spec_check_reports_nested_path_and_docs_keys(self):
+        """Problems name the full attribute path, including inside a docs block."""
+        base = yaml.safe_load(BAD_SPEC_YAML)
+        problems = check_base_spec(base)
+        self.assertTrue(
+            any("attribute 'nested->deep': unrecognized key 'chioces'" in p for p in problems)
+        )
+        self.assertTrue(any("'titel' in its 'docs' block" in p for p in problems))
+
+    def test_spec_check_flags_missing_type(self):
+        base = yaml.safe_load(BAD_SPEC_YAML)
+        problems = check_base_spec(base)
+        self.assertTrue(any("attribute 'untyped': no 'type' declared" in p for p in problems))
+
+    def test_bad_spec_warns_by_default(self):
+        """A questionable spec still loads, but says so."""
+        specfile = 'spec-check-base.yaml'
+        with open(specfile, 'w') as f:
+            f.write(BAD_SPEC_YAML.replace(UNTYPED_ATTRIBUTE, ''))
+        with self.assertWarns(YclepticSpecWarning) as cm:
+            Y = Yclept(specfile, userdict={'a_opts': 'red'})
+        self.assertIn('does not act on', str(cm.warning))
+        self.assertEqual(Y['user']['a_opts'], 'red')
+
+    def test_attribute_with_no_type_reports_cleanly(self):
+        """A spec attribute with no declared type is an error, not a KeyError."""
+        specfile = 'spec-check-base.yaml'
+        with open(specfile, 'w') as f:
+            f.write(BAD_SPEC_YAML)
+        with self.assertWarns(YclepticSpecWarning):
+            with self.assertRaises(YclepticError) as cm:
+                Yclept(specfile, userdict={})
+        self.assertIn('declares no type', str(cm.exception))
+
+    def test_bad_spec_raises_under_strict_spec(self):
+        specfile = 'spec-check-base.yaml'
+        with open(specfile, 'w') as f:
+            f.write(BAD_SPEC_YAML)
+        with self.assertRaises(YclepticError) as cm:
+            Yclept(specfile, userdict={}, strict_spec=True)
+        self.assertIn("unrecognized key 'options'", str(cm.exception))
+
+    def test_good_spec_neither_warns_nor_raises(self):
+        import warnings
+
+        with warnings.catch_warnings():
+            warnings.simplefilter('error', YclepticSpecWarning)
+            Yclept(BFILE, strict_spec=True)
+
+    def test_check_spec_cli_reports_and_exits_nonzero(self):
+        """The check-spec subcommand gates CI on a clean base spec."""
+        from argparse import Namespace
+
+        specfile = 'spec-check-base.yaml'
+        with open(specfile, 'w') as f:
+            f.write(BAD_SPEC_YAML)
+        with open('console-out.txt', 'w') as f:
+            with redirect_stderr(f):
+                with self.assertRaises(SystemExit) as cm:
+                    check_spec(Namespace(config=specfile))
+        self.assertEqual(cm.exception.code, 1)
+        with open('console-out.txt', 'r') as f:
+            self.assertIn("unrecognized key 'options'", f.read())
+
+        with open('console-out.txt', 'w') as f:
+            with redirect_stdout(f):
+                check_spec(Namespace(config=BFILE))
+        with open('console-out.txt', 'r') as f:
+            self.assertIn('no unrecognized keys or types', f.read())
+
     def test_makedoc(self):
         Y = Yclept(BFILE)
         Y.make_doctree('ydoc')
@@ -323,6 +467,8 @@ Single-valued attributes:
 
   * ``attribute_5``: This is a description of Attribute 5
 
+    Allowed values: ``a``, ``b``, ``c``
+
 
 
 Subattributes:

{ycleptic-2.2.2 → ycleptic-2.3.0}/ycleptic/__init__.py

@@ -12,6 +12,6 @@ except PackageNotFoundError:
 logging.getLogger(__name__).addHandler(logging.NullHandler())
 
 from ycleptic.yclept import Yclept
-from ycleptic.errors import YclepticError
+from ycleptic.errors import YclepticError, YclepticSpecWarning
 
-__all__ = ['Yclept', 'YclepticError']
+__all__ = ['Yclept', 'YclepticError', 'YclepticSpecWarning']

{ycleptic-2.2.2 → ycleptic-2.3.0}/ycleptic/cli.py

@@ -6,9 +6,11 @@ Command-line interface for ycleptic
 
 from __future__ import annotations
 import sys
+import yaml
 from .yclept import Yclept
 import argparse as ap
 import textwrap
+from .speccheck import check_base_spec, format_problems
 from .stringthings import oxford, banner_message
 from .errors import YclepticError
 
@@ -44,18 +46,35 @@ def config_help(args):
     )
 
 
+def check_spec(args):
+    """
+    Reports any declarations in a base config file that ycleptic ignores.
+    """
+    with open(args.config, 'r') as f:
+        base = yaml.safe_load(f)
+    problems = check_base_spec(base)
+    if not problems:
+        print(f'{args.config}: no unrecognized keys or types')
+        return
+    print(format_problems(problems, args.config), file=sys.stderr)
+    sys.exit(1)
+
+
 def cli():
     commands = {
         'make-doc': makedoc,
         'config-help': config_help,
+        'check-spec': check_spec,
     }
     helps = {
         'make-doc': 'Makes a sphinx/rtd-style doctree from the base config file provided and, optionally, a root node',
         'config-help': 'Help on a base config file',
+        'check-spec': 'Reports declarations in a base config file that ycleptic ignores',
     }
     descs = {
         'make-doc': 'If you provide the name of a base configuration file for your app, and optionally, a root attribute, this command will generate a sphinx/rtd-style doctree',
         'config-help': 'If you provide the name of a base configuration file for your app, you can use this command to explore it the way a user would in your app',
+        'check-spec': 'Reads a base configuration file and reports every key or type name ycleptic does not recognize, each of which is silently ignored when configs are validated.  Exits nonzero if any are found, so it can gate a CI run',
     }
     parser = ap.ArgumentParser(
         description=textwrap.dedent(banner_message), formatter_class=ap.RawDescriptionHelpFormatter
@@ -84,6 +103,9 @@ def cli():
         choices=['paragraph', 'comment', 'rubric', 'note', 'raw-html'],
         help='footer style for the generated documentation; one of "paragraph", "comment", "rubric", "note", or "raw-html"; default %(default)s',
     )
+    command_parsers['check-spec'].add_argument(
+        'config', type=str, default=None, help='input base configuration file in YAML format'
+    )
     command_parsers['config-help'].add_argument(
         'config', type=str, default=None, help='input base configuration file in YAML format'
     )

{ycleptic-2.2.2 → ycleptic-2.3.0}/ycleptic/errors.py

@@ -17,3 +17,16 @@ class YclepticError(Exception):
     catches :class:`YclepticError` and reports it as a clean, traceback-free
     error message.
     """
+
+
+class YclepticSpecWarning(UserWarning):
+    """
+    Issued when a base config specification contains a declaration ycleptic
+    ignores, such as a misspelled key or an unrecognized type name.
+
+    Such a declaration does nothing, so an attribute its author believes is
+    constrained may in fact accept any value.  This is a warning rather than an
+    error so that existing specifications keep loading; construct
+    :class:`~ycleptic.yclept.Yclept` with ``strict_spec=True`` to raise
+    :class:`YclepticError` instead.
+    """

{ycleptic-2.2.2 → ycleptic-2.3.0}/ycleptic/makedoc.py

@@ -97,6 +97,9 @@ def make_doc(
             default = sv.get('default', None)
             default_text = f' (default: {default})' if default is not None else ''
             fp.write(f'  * ``{sv["name"]}``: {sv["text"]}{default_text}\n\n')
+            if 'choices' in sv:
+                allowed = ', '.join(f'``{c}``' for c in sv['choices'])
+                fp.write(f'    Allowed values: {allowed}\n\n')
             sv_example = sv.get('docs', {}).get('example', {})
             if sv_example:
                 fp.write('    Example:\n\n')

ycleptic-2.3.0/ycleptic/speccheck.py

@@ -0,0 +1,161 @@
+# Author: Cameron F. Abrams <cfa22@drexel.edu>
+
+"""
+Validation of the base config specification itself
+
+A base config is data, and ycleptic reads only the keys it recognizes.  A
+misspelled key or type name is therefore discarded without comment, leaving the
+schema author with a declaration that silently does nothing --- a
+``choices:`` list that never constrains anything, for instance.  The checks
+here look over a base spec as it is loaded and report those declarations.
+"""
+
+from __future__ import annotations
+
+import difflib
+
+#: Keys ycleptic reads from an attribute node of a base config.
+KNOWN_ATTRIBUTE_KEYS = frozenset(
+    {
+        'name',
+        'type',
+        'text',
+        'default',
+        'required',
+        'choices',
+        'case_sensitive',
+        'attributes',
+        'docs',
+    }
+)
+
+#: Keys ycleptic reads from an attribute's ``docs`` block.
+KNOWN_DOCS_KEYS = frozenset({'title', 'text', 'example'})
+
+#: Keys ycleptic reads from the top level of a base config.
+KNOWN_TOP_KEYS = frozenset({'attributes', 'docs'})
+
+#: Type names ycleptic recognizes.
+KNOWN_TYPES = frozenset({'str', 'int', 'float', 'bool', 'tuple', 'list', 'dict'})
+
+# Misspellings common enough to name outright rather than leave to difflib.
+_KEY_ALIASES = {
+    'option': 'choices',
+    'options': 'choices',
+    'allowed': 'choices',
+    'allowed_values': 'choices',
+    'attribute': 'attributes',
+    'description': 'text',
+    'help': 'text',
+    'subattributes': 'attributes',
+}
+
+_TYPE_ALIASES = {
+    'array': 'list',
+    'boolean': 'bool',
+    'double': 'float',
+    'integer': 'int',
+    'map': 'dict',
+    'mapping': 'dict',
+    'number': 'float',
+    'object': 'dict',
+    'real': 'float',
+    'sequence': 'list',
+    'string': 'str',
+    'text': 'str',
+}
+
+
+def _suggest(word, known, aliases):
+    """
+    Return a ``did you mean`` clause for ``word``, or an empty string.
+    """
+    if not isinstance(word, str):
+        return ''
+    alias = aliases.get(word.lower())
+    if alias is None:
+        close = difflib.get_close_matches(word.lower(), sorted(known), n=1, cutoff=0.7)
+        alias = close[0] if close else None
+    return f" (did you mean '{alias}'?)" if alias else ''
+
+
+def _path_str(path: list[str]) -> str:
+    return '->'.join(path) if path else 'the top level'
+
+
+def _check_node(node: dict, path: list[str], problems: list[str]):
+    where = f"attribute '{_path_str(path)}'"
+
+    for key in node:
+        if key not in KNOWN_ATTRIBUTE_KEYS:
+            problems.append(
+                f'{where}: unrecognized key '
+                f"'{key}'{_suggest(key, KNOWN_ATTRIBUTE_KEYS, _KEY_ALIASES)}; it is ignored"
+            )
+
+    typ = node.get('type')
+    if typ is None:
+        problems.append(f"{where}: no 'type' declared")
+    elif typ not in KNOWN_TYPES:
+        problems.append(
+            f"{where}: unrecognized type '{typ}'"
+            f'{_suggest(typ, KNOWN_TYPES, _TYPE_ALIASES)}; the attribute is left unvalidated'
+        )
+    elif 'choices' in node and typ != 'str':
+        problems.append(
+            f"{where}: 'choices' is only enforced on 'str' attributes, "
+            f"and this one is '{typ}'; the allowed values are not applied"
+        )
+
+    docs = node.get('docs')
+    if isinstance(docs, dict):
+        for key in docs:
+            if key not in KNOWN_DOCS_KEYS:
+                problems.append(
+                    f"{where}: unrecognized key '{key}' in its 'docs' block"
+                    f'{_suggest(key, KNOWN_DOCS_KEYS, {})}; it is ignored'
+                )
+
+    for sub in node.get('attributes', []) or []:
+        if isinstance(sub, dict):
+            _check_node(sub, path + [str(sub.get('name', '?'))], problems)
+
+
+def check_base_spec(base: dict) -> list[str]:
+    """
+    Look over a base config specification and report declarations ycleptic ignores.
+
+    Parameters
+    ----------
+    base : dict
+        A base config specification, as loaded from a base config file.
+
+    Returns
+    -------
+    list of str
+        One message per problem found, in the order encountered.  Empty if the
+        specification uses only keys and type names ycleptic recognizes.
+    """
+    problems: list[str] = []
+    if not isinstance(base, dict):
+        return problems
+    for key in base:
+        if key not in KNOWN_TOP_KEYS:
+            problems.append(
+                f'the top level: unrecognized key '
+                f"'{key}'{_suggest(key, KNOWN_TOP_KEYS, _KEY_ALIASES)}; it is ignored"
+            )
+    for node in base.get('attributes', []) or []:
+        if isinstance(node, dict):
+            _check_node(node, [str(node.get('name', '?'))], problems)
+    return problems
+
+
+def format_problems(problems: list[str], basefile: str = '') -> str:
+    """
+    Render ``problems`` as a single multi-line report.
+    """
+    src = f' {basefile}' if basefile else ''
+    ess = 's' if len(problems) > 1 else ''
+    head = f'base config{src} has {len(problems)} declaration{ess} ycleptic does not act on:'
+    return '\n'.join([head] + [f'  - {p}' for p in problems])

{ycleptic-2.2.2 → ycleptic-2.3.0}/ycleptic/stringthings.py

@@ -5,6 +5,8 @@ Various string manipulation functions for ycleptic
 """
 
 from __future__ import annotations
+
+from typing import NoReturn
 import yaml
 from datetime import date
 from . import __version__
@@ -19,7 +21,7 @@ banner_message = """
     """.format(__version__)
 
 
-def raise_clean(ErrorInstance):
+def raise_clean(ErrorInstance) -> NoReturn:
     """
     Raises a :class:`~ycleptic.errors.YclepticError` carrying the message of
     the given exception instance.

{ycleptic-2.2.2 → ycleptic-2.3.0}/ycleptic/walkers.py

@@ -106,6 +106,19 @@ def _scalar_type_ok(typ: str, value) -> bool:
     return True
 
 
+def _declared_type(dx: dict, dname: str) -> str:
+    """
+    Return the declared type of attribute spec ``dx``, or report its absence.
+
+    Every attribute must declare a type; without one there is nothing to
+    validate the user's value against.
+    """
+    typ = dx.get('type')
+    if typ is None:
+        raise_clean(ValueError(f"Attribute '{dx.get('name', '?')}' of '{dname}' declares no type."))
+    return typ
+
+
 def dwalk(D: dict, I: dict):
     """
     Recursively process the user's config-dict I by walking recursively through it
@@ -143,7 +156,7 @@ def dwalk(D: dict, I: dict):
         dx = D['attributes'][tidx]
         # logger.debug(f' d {d}')
         # get its type
-        typ = dx['type']
+        typ = _declared_type(dx, dname)
         if typ == 'dict' and (d in I and not isinstance(I[d], dict)):
             raise_clean(
                 ValueError(f"Attribute '{d}' of '{dname}' must be a dict; found {type(I[d])}.")
@@ -261,7 +274,7 @@ def lwalk(D: dict, L: list[dict]):
             )
         tidx = tld.index(itemname)
         dx = D['attributes'][tidx]
-        typ = dx['type']
+        typ = _declared_type(dx, D['name'])
         if typ in ['str', 'int', 'float']:
             # because a list attribute indicates an ordered sequence of tasks and we expect each
             # task to be a dictionary specifying the task and not a single scalar value,

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

@@ -7,12 +7,16 @@ from __future__ import annotations
 import logging
 import sys
 import textwrap
+import warnings
 from pathlib import Path
 import yaml
 from collections import UserDict
 from argparse import Namespace
 from . import __version__
+from .errors import YclepticSpecWarning
 from .makedoc import make_doc
+from .speccheck import check_base_spec, format_problems
+from .stringthings import raise_clean
 from .walkers import make_def, mwalk, dwalk
 
 logger = logging.getLogger(__name__)
@@ -34,10 +38,20 @@ class Yclept(UserDict):
         A dictionary of user-defined configurations. Optional; used instead of ``userfile`` when provided.
     rcfile : str
         The path to a resource config file that extends the base config. Optional.
+    strict_spec : bool
+        If True, a base config containing declarations ycleptic ignores --- a
+        misspelled key or an unrecognized type name --- raises
+        :class:`~ycleptic.errors.YclepticError` instead of issuing a
+        :class:`~ycleptic.errors.YclepticSpecWarning`.  Optional; defaults to False.
     """
 
     def __init__(
-        self, basefile: str, userfile: str = '', userdict: dict | None = None, rcfile: str = ''
+        self,
+        basefile: str,
+        userfile: str = '',
+        userdict: dict | None = None,
+        rcfile: str = '',
+        strict_spec: bool = False,
     ):
         data = {}
         with open(basefile, 'r') as f:
@@ -46,6 +60,12 @@ class Yclept(UserDict):
             with open(rcfile, 'r') as f:
                 rc = yaml.safe_load(f)
                 mwalk(data['base'], rc)
+        problems = check_base_spec(data['base'])
+        if problems:
+            report = format_problems(problems, basefile)
+            if strict_spec:
+                raise_clean(ValueError(report))
+            warnings.warn(report, YclepticSpecWarning, stacklevel=2)
         super().__init__(data)
         if userdict is None:
             userdict = {}

ycleptic-2.2.2/docs/source/usage.rst

@@ -1,16 +0,0 @@
-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::
-   :maxdepth: 1
-
-   usage/quickstart
-   usage/class
-   usage/the_base_config
-   usage/the_user_config
-   usage/interactive_help
-   usage/resource_file
-   usage/yclept_config-help
-   usage/yclept_makedoc