cmdkit 2.7.7__tar.gz → 2.8.0__tar.gz

{cmdkit-2.7.7 → cmdkit-2.8.0}/PKG-INFO

@@ -1,29 +1,31 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: cmdkit
-Version: 2.7.7
+Version: 2.8.0
 Summary: A command-line utility toolkit for Python.
-Home-page: https://cmdkit.readthedocs.io
-License: Apache-2.0
 Keywords: command-line,utility,toolkit
 Author: Geoffrey Lentner
-Author-email: glentner@purdue.edu
-Requires-Python: >=3.9,<4.0
+Author-email: Geoffrey Lentner <glentner@purdue.edu>
+License-Expression: Apache-2.0
+License-File: LICENSE
 Classifier: Development Status :: 5 - Production/Stable
-Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 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
-Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
-Provides-Extra: toml
-Provides-Extra: yaml
-Requires-Dist: pyyaml (>=6.0.1,<7.0.0) ; extra == "yaml"
-Requires-Dist: tomli (>=2.1.0,<3.0.0) ; extra == "toml"
-Requires-Dist: tomli-w (>=1.1.0,<2.0.0) ; extra == "toml"
+Classifier: Programming Language :: Python :: 3.14
+Classifier: License :: OSI Approved :: Apache Software License
+Requires-Dist: tomli>=2.1.0,<3.0.0 ; extra == 'toml'
+Requires-Dist: tomli-w>=1.1.0,<2.0.0 ; extra == 'toml'
+Requires-Dist: pyyaml>=6.0.1,<7.0.0 ; extra == 'yaml'
+Requires-Python: >=3.9, <4.0
+Project-URL: Homepage, https://cmdkit.readthedocs.io
 Project-URL: Documentation, https://cmdkit.readthedocs.io
 Project-URL: Repository, https://github.com/glentner/cmdkit
+Provides-Extra: toml
+Provides-Extra: yaml
 Description-Content-Type: text/x-rst
 
 CmdKit
@@ -92,4 +94,3 @@ Contributions are welcome in the form of suggestions for additional features, pu
 new features or bug fixes, etc. If you find bugs or have questions, open an *Issue* here. If and
 when the project grows, a code of conduct will be provided along side a more comprehensive set of
 guidelines for contributing; until then, just be nice.
-

cmdkit-2.8.0/pyproject.toml

@@ -0,0 +1,77 @@
+[project]
+name = "cmdkit"
+version = "2.8.0"
+description = "A command-line utility toolkit for Python."
+readme = "README.rst"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+keywords = [
+    "command-line",
+    "utility",
+    "toolkit",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "License :: OSI Approved :: Apache Software License",
+]
+requires-python = ">=3.9,<4.0"
+dependencies = []
+
+[[project.authors]]
+name = "Geoffrey Lentner"
+email = "glentner@purdue.edu"
+
+[project.optional-dependencies]
+toml = [
+    "tomli>=2.1.0,<3.0.0",
+    "tomli-w>=1.1.0,<2.0.0",
+]
+yaml = ["pyyaml>=6.0.1,<7.0.0"]
+
+[project.urls]
+Homepage = "https://cmdkit.readthedocs.io"
+Documentation = "https://cmdkit.readthedocs.io"
+Repository = "https://github.com/glentner/cmdkit"
+
+[dependency-groups]
+dev = [
+    "tomli>=2.1.0,<3.0.0",
+    "tomli-w>=1.1.0,<2.0.0",
+    "pyyaml>=6.0.1,<7.0.0",
+    "pytest>=7.4.4,<8.0.0",
+    "hypothesis>=6.92.6,<7.0.0",
+    "sphinx-autobuild>=2021.3.14,<2022.0.0",
+]
+docs = [
+    "sphinx>=7.2.6,<8.0.0",
+    "sphinx-sitemap>=2.5.1,<3.0.0",
+    "sphinx-autobuild>=2021.3.14,<2022.0.0",
+    "sphinx-copybutton>=0.5.2,<0.6.0",
+    "sphinxext-opengraph>=0.9.1,<0.10.0",
+    "sphinxcontrib-details-directive>=0.1.0,<0.2.0",
+    "sphinx-toolbox>=3.5.0,<4.0.0",
+    "pydata-sphinx-theme>=0.15.1,<0.16.0",
+    "enum-tools[sphinx]>=0.10.0,<0.11.0",
+    "docutils>=0.21.1,<0.22.0",
+    "setuptools<82",
+]
+
+[build-system]
+requires = ["uv_build>=0.13.7,<0.14.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+addopts = ["--strict-markers"]
+markers = [
+    "unit: Unit tests are short, interface driven tests on discrete components.",
+    "integration: Integration tests are often longer and deal with the interaction between systems.",
+    "parameterize: Place holder for parameterized tests (not a real type).",
+]

cmdkit-2.8.0/pyproject.toml.orig

@@ -0,0 +1,71 @@
+[project]
+name = "cmdkit"
+version = "2.8.0"
+description = "A command-line utility toolkit for Python."
+readme = "README.rst"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Geoffrey Lentner", email = "glentner@purdue.edu" },
+]
+keywords = ["command-line", "utility", "toolkit"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "License :: OSI Approved :: Apache Software License",
+]
+requires-python = ">=3.9,<4.0"
+dependencies = []
+
+[project.optional-dependencies]
+toml = ["tomli>=2.1.0,<3.0.0", "tomli-w>=1.1.0,<2.0.0"]
+yaml = ["pyyaml>=6.0.1,<7.0.0"]
+
+[project.urls]
+Homepage = "https://cmdkit.readthedocs.io"
+Documentation = "https://cmdkit.readthedocs.io"
+Repository = "https://github.com/glentner/cmdkit"
+
+[dependency-groups]
+dev = [
+    "tomli>=2.1.0,<3.0.0",
+    "tomli-w>=1.1.0,<2.0.0",
+    "pyyaml>=6.0.1,<7.0.0",
+    "pytest>=7.4.4,<8.0.0",
+    "hypothesis>=6.92.6,<7.0.0",
+    "sphinx-autobuild>=2021.3.14,<2022.0.0",
+]
+docs = [
+    "sphinx>=7.2.6,<8.0.0",
+    "sphinx-sitemap>=2.5.1,<3.0.0",
+    "sphinx-autobuild>=2021.3.14,<2022.0.0",
+    "sphinx-copybutton>=0.5.2,<0.6.0",
+    "sphinxext-opengraph>=0.9.1,<0.10.0",
+    "sphinxcontrib-details-directive>=0.1.0,<0.2.0",
+    "sphinx-toolbox>=3.5.0,<4.0.0",
+    "pydata-sphinx-theme>=0.15.1,<0.16.0",
+    "enum-tools[sphinx]>=0.10.0,<0.11.0",
+    "docutils>=0.21.1,<0.22.0",
+    # sphinxcontrib-details-directive imports pkg_resources, which setuptools 82 removed;
+    # a uv environment holds only what is declared, so setuptools is named here
+    "setuptools<82",
+]
+
+[build-system]
+requires = ["uv_build>=0.13.7,<0.14.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+addopts = ["--strict-markers", ]
+markers = [
+    "unit: Unit tests are short, interface driven tests on discrete components.",
+    "integration: Integration tests are often longer and deal with the interaction between systems.",
+    "parameterize: Place holder for parameterized tests (not a real type).",
+]

{cmdkit-2.7.7 → cmdkit-2.8.0}/src/cmdkit/__init__.py

@@ -30,4 +30,7 @@ __all__ = [
 __version__ = get_version('cmdkit')
 
 # null-handler for library interface
-Logger.with_name(__name__).addHandler(NullHandler())
+_null_handler = NullHandler()
+_null_handler._cmdkit_library_handler = True
+Logger.with_name(__name__).addHandler(_null_handler)
+del _null_handler

{cmdkit-2.7.7 → cmdkit-2.8.0}/src/cmdkit/app.py

@@ -10,6 +10,7 @@ from typing import List, Dict, Callable, NamedTuple, Type, TypeVar
 
 # standard libs
 import abc
+import sys
 import logging
 
 # internal libs
@@ -27,6 +28,41 @@ TAppGrp = TypeVar('TAppGrp', bound='ApplicationGroup')
 log = logging.getLogger(__name__)
 
 
+def _hidden_by_null_handler(logger: logging.Logger, level: int, msg: object) -> bool:
+    """
+    True if the :class:`logging.NullHandler` cmdkit attaches to its logger at import is the only
+    reason Python's last-resort handler did not print a record with `msg` at `level` from `logger`.
+
+    This follows :meth:`logging.Logger.handle` and :meth:`logging.Logger.callHandlers` in order,
+    and is false wherever Python would print nothing anyway: the logger is not enabled for `level`
+    (a disabled logger, a logger level above `level`, or :func:`logging.disable`), the logger's
+    own filters reject the record, or :data:`logging.lastResort` is unset or above `level`.
+    Otherwise the logger and its ancestors are searched for as long as they propagate. Any handler
+    found, whatever its level, other than cmdkit's own (recognised by the mark set on it where the
+    package attaches it) means the application has configured logging: false. That includes a
+    :class:`logging.NullHandler` the application adds to the `cmdkit` logger itself to silence it.
+    If no handler is found at all, Python's last resort has already printed the record: also
+    false, so the message appears only once.
+    """
+    if not logger.isEnabledFor(level):
+        return False
+    if not logger.filter(logger.makeRecord(logger.name, level, '(unknown file)', 0, msg, (), None)):
+        return False
+    if logging.lastResort is None or level < logging.lastResort.level:
+        return False
+    found = False
+    current = logger
+    while current is not None:
+        for handler in current.handlers:
+            if getattr(handler, '_cmdkit_library_handler', False) is not True:
+                return False
+            found = True
+        if not current.propagate:
+            break
+        current = current.parent
+    return found
+
+
 # NOTE: In next major release this will be made into an Enum
 class ExitStatus(NamedTuple):
     """Collection of exit status values."""
@@ -96,8 +132,22 @@ class Application(abc.ABC):
         Entry-point for application.
         This is a try-except block that handles standard scenarios.
 
+        An :class:`~cmdkit.cli.ArgumentError` is passed to :data:`~Application.log_critical`
+        and ``exit_status.bad_argument`` is returned. If ``log_critical`` is the default and the
+        :class:`~logging.NullHandler` cmdkit attaches to its own logger is the only reason
+        Python's last-resort handler did not print the record (no handler of the application's
+        is found, and the ``cmdkit.app`` logger is neither silenced nor filtering the record
+        out), the message is also written as is to ``sys.stderr``, followed by a newline.
+        Where no handler is found at all, Python's last resort prints the record itself, and
+        that line stands alone. A :class:`~logging.NullHandler` the application adds to the
+        ``cmdkit`` logger is a handler of the application's, and keeps the message silent.
+        Without a ``sys.stderr`` (it is ``None``) the message is skipped, and a failure to
+        write it (a closed stream or a broken pipe) is ignored, so ``main`` still returns
+        ``exit_status.bad_argument``.
+
         See Also:
             :data:`~Application.exceptions`
+            :data:`~Application.log_critical`
         """
         try:
             if not cmdline:
@@ -124,6 +174,12 @@ class Application(abc.ABC):
 
         except ArgumentError as error:
             cls.log_critical(error)
+            if cls.log_critical == log.critical and _hidden_by_null_handler(log, logging.CRITICAL, error):
+                if sys.stderr is not None:
+                    try:
+                        print(error, file=sys.stderr)
+                    except (OSError, ValueError):
+                        pass
             return exit_status.bad_argument
 
         except KeyboardInterrupt:

{cmdkit-2.7.7 → cmdkit-2.8.0}/src/cmdkit/config.py

@@ -10,7 +10,7 @@ local files and your environment.
 
 # type annotations
 from __future__ import annotations
-from typing import Tuple, List, Dict, TypeVar, Callable, Union, Any
+from typing import Tuple, List, Dict, TypeVar, Callable, Union, Any, Mapping
 
 # standard libs
 from collections import Counter
@@ -33,6 +33,85 @@ class ConfigurationError(Exception):
     """Exception specific to configuration errors."""
 
 
+_MISSING = object()
+
+
+def _variant_siblings(key: Any) -> List[str]:
+    """The other keys that are a variant of a name `key` is a variant of."""
+    if not isinstance(key, str):
+        return []
+    names = [key]
+    if key.endswith('_env'):
+        names.append(key[:-4])
+    if key.endswith('_eval'):
+        names.append(key[:-5])
+    return [other for name in names for other in (name, f'{name}_env', f'{name}_eval') if other != key]
+
+
+def _drop_displaced_variants(target: dict, new: Mapping) -> None:
+    """
+    Remove from `target` every variant of a name that `new` sets a different variant of,
+    at every level where the depth-first update will descend.
+    """
+    for key, value in new.items():
+        for other in _variant_siblings(key):
+            if other in target and other not in new:
+                del target[other]
+        if isinstance(value, dict) and isinstance(target.get(key), dict):
+            _drop_displaced_variants(target[key], value)
+
+
+def _apply_layer(target: NSCoreMixin, new: Mapping) -> None:
+    """Depth-first update of `target` with `new`, where the variants `new` sets displace the others."""
+    _drop_displaced_variants(target, new)
+    NSCoreMixin.update(target, new)
+
+
+def _value_at(mapping: Any, path: Tuple[Any, ...]) -> Any:
+    """The value at `path` through nested mappings, or `_MISSING`."""
+    for key in path:
+        if not isinstance(mapping, dict) or key not in mapping:
+            return _MISSING
+        mapping = mapping[key]
+    return mapping
+
+
+def _lacks(mapping: Any, path: Tuple[Any, ...]) -> bool:
+    """Whether item access along `path` raises `KeyError`: a mapping on the way lacks the next key."""
+    for key in path:
+        if not isinstance(mapping, dict):
+            return False
+        if key not in mapping:
+            return True
+        mapping = mapping[key]
+    return False
+
+
+def _depth_held(mapping: Any, path: Tuple[Any, ...]) -> int:
+    """How many leading keys of `path` are held through nested mappings."""
+    for depth, key in enumerate(path):
+        if not isinstance(mapping, dict) or key not in mapping:
+            return depth
+        mapping = mapping[key]
+    return len(path)
+
+
+def _displaced(sources: List[Mapping], path: Tuple[Any, ...]) -> bool:
+    """
+    Whether a source sets another variant of a key on `path` in that key's place,
+    and not the key itself, above a source that holds `path` down to that key.
+    """
+    held = set()
+    for source in sources:
+        for depth, key in enumerate(path):
+            parent = _value_at(source, path[:depth])
+            if depth in held and isinstance(parent, dict) and key not in parent \
+                    and any(other in parent for other in _variant_siblings(key)):
+                return True
+        held.update(range(_depth_held(source, path)))
+    return False
+
+
 class Configuration(NSCoreMixin):
     """
     An ordered collection of `Namespace` dictionaries.
@@ -54,6 +133,24 @@ class Configuration(NSCoreMixin):
 
         >>> conf.namespaces.one.x
         1
+
+    A parameter `name` and its `name_env` and `name_eval` variants are one key across
+    the layers: the highest layer that sets any of them decides, and only the variants
+    it sets remain in the merged view. Within a single layer, two variants of one name
+    are still ambiguous.
+
+    Example:
+        >>> conf = Configuration(one=Namespace({'db': {'password': 'secret'}}),
+        ...                      two=Namespace({'db': {'password_eval': 'echo other'}}))
+
+        >>> dict(conf)
+        {'db': Namespace({'password_eval': 'echo other'})}
+
+        >>> conf.db.password
+        'other'
+
+        >>> conf.which('db', 'password_eval')
+        'two'
     """
 
     local: Namespace  # NOTE: used to track changes to the 'self'
@@ -89,7 +186,7 @@ class Configuration(NSCoreMixin):
         for name, mapping in others.items():
             if name != '_':
                 self.namespaces[name] = Namespace(mapping)
-                super().update(self.namespaces[name])
+                _apply_layer(self, self.namespaces[name])
             else:
                 self.local.update(mapping)
 
@@ -180,6 +277,8 @@ class Configuration(NSCoreMixin):
             Namespace({'x': 1, 'y': 3})
         """
         namespaces = Namespace({**self.namespaces, '_': self.local})
+        if _lacks(self, path) and _displaced(list(namespaces.values()), path):
+            raise KeyError(f'Not found: {path}')
         for label in reversed(list(namespaces.keys())):
             try:
                 sub = namespaces[label]
@@ -231,7 +330,7 @@ class Configuration(NSCoreMixin):
 
     def __setattr__(self, name: str, value: Any) -> None:
         """Intercept parameter assignment."""
-        if name in self:
+        if name in self or any(other in self for other in _variant_siblings(name)):
             self.update({name: value})
         else:
             super().__setattr__(name, value)
@@ -247,6 +346,9 @@ class Configuration(NSCoreMixin):
             Instead, overrides have been implemented to capture these changes in a `local` namespace.
             If you ask :func:`which` namespace a parameter has come from, and it was an in-place change,
             it will be considered a member of the "_" namespace.
+            An in-place change follows the same rule as the layers for `_env` and `_eval`
+            variants: setting one variant of a name replaces any other variant of that name,
+            both in the "_" namespace and in the merged view.
 
         Example:
             >>> conf = Configuration(a=Namespace(x=1))
@@ -268,8 +370,8 @@ class Configuration(NSCoreMixin):
             >>> dict(conf)
             {'x': 2, 'y': 3}
         """
-        self.local.update(*args, **kwargs)
-        super().update(*args, **kwargs)
+        _apply_layer(self.local, dict(*args, **kwargs))
+        _apply_layer(self, dict(*args, **kwargs))
 
     def pop(self, *args, **kwargs) -> Any:
         """

cmdkit-2.7.7/pyproject.toml

@@ -1,66 +0,0 @@
-[tool.poetry]
-name = "cmdkit"
-version = "2.7.7"
-description = "A command-line utility toolkit for Python."
-readme = "README.rst"
-license = "Apache-2.0"
-homepage = "https://cmdkit.readthedocs.io"
-documentation = "https://cmdkit.readthedocs.io"
-repository = "https://github.com/glentner/cmdkit"
-authors = [
-    "Geoffrey Lentner <glentner@purdue.edu>"
-]
-keywords = ["command-line", "utility", "toolkit"]
-classifiers = [
-    "Development Status :: 5 - Production/Stable",
-    "Topic :: Software Development :: Libraries :: Application Frameworks",
-    "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.9",
-    "Programming Language :: Python :: 3.10",
-    "Programming Language :: Python :: 3.11",
-    "Programming Language :: Python :: 3.12",
-    "Programming Language :: Python :: 3.13",
-    "License :: OSI Approved :: Apache Software License",
-]
-
-[tool.poetry.dependencies]
-python = ">=3.9,<4.0"
-tomli = {version = "^2.1.0", optional = true}
-tomli-w = {version = "^1.1.0", optional = true}
-pyyaml = {version = "^6.0.1", optional = true}
-
-[tool.poetry.extras]
-toml = ['tomli', 'tomli-w']
-yaml = ['pyyaml']
-
-[tool.poetry.group.docs.dependencies]
-sphinx = "^7.2.6"
-sphinx-sitemap = "^2.5.1"
-sphinx-autobuild = "^2021.3.14"
-sphinx-copybutton = "^0.5.2"
-sphinxext-opengraph = "^0.9.1"
-sphinxcontrib-details-directive = "^0.1.0"
-sphinx-toolbox = "^3.5.0"
-pydata-sphinx-theme = "^0.15.1"
-enum-tools = {extras = ["sphinx"], version = "^0.10.0"}
-docutils = "^0.21.1"  # NOTE: https://github.com/python-poetry/poetry/issues/9293
-
-[tool.poetry.group.dev.dependencies]
-tomli = "^2.1.0"
-tomli-w = "^1.1.0"
-pyyaml = "^6.0.1"
-pytest = "^7.4.4"
-hypothesis = "^6.92.6"
-sphinx-autobuild = "^2021.3.14"
-
-[build-system]
-requires = ["poetry-core>=1.0.0"]
-build-backend = "poetry.core.masonry.api"
-
-[tool.pytest.ini_options]
-addopts = ["--strict-markers", ]
-markers = [
-    "unit: Unit tests are short, interface driven tests on discrete components.",
-    "integration: Integration tests are often longer and deal with the interaction between systems.",
-    "parameterize: Place holder for parameterized tests (not a real type).",
-]