Release 4.12

HISTORY

@@ -1,3 +1,23 @@
+4.12
+====
+
+Changes
+-------
+
+- Introduction of typed_settings, providing a cleaner way to access default settings
+  that supports auto-completion and type inference. And preparing the way for more
+  in-depth checks that ensure settings values match the expected types.
+
+- Support ``Literal`` types in CLI. Maps str and int literals to choices.
+
+- Support sequences of Enum values in the CLI. This is implemented via the
+  ``AppendEnumValue`` and ``AppendEnumName`` actions.
+
+- Migrate from pkg_resources to the standardised builtin importlib.metadata.
+
+- Fix for handling events/callbacks on classes where the parent has __slots__ defined.
+
+
 4.11.0
 ======
 

docs/reference/conf/typed-settings.rst

@@ -0,0 +1 @@
+.. automodule:: pyapp.typed_settings

docs/reference/index.rst

@@ -10,7 +10,7 @@ Contents:
    app
    checks
    conf
-   conf/base_settings
+   conf/typed-settings
    conf/helpers
    events
    injection

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "pyapp"
-version = "4.11.0"
+version = "4.12.0"
 description = "A Python application framework - Let us handle the boring stuff!"
 authors = ["Tim Savage <tim@savage.company>"]
 license = "BSD-3-Clause"
@@ -37,6 +37,7 @@ python = "^3.8"
 argcomplete = "*"
 colorama = "*"
 yarl = "*"
+importlib_metadata = {version = "*", python = "<=3.9"}
 
 pyyaml = {version = "*", optional = true }
 toml = {version = "*", optional = true }

src/pyapp/app/argument_actions.py

@@ -14,6 +14,10 @@
 
 .. autoclass:: EnumName
 
+.. autoclass:: AppendEnumValue
+
+.. autoclass:: AppendEnumName
+
 
 Date and Time types
 ~~~~~~~~~~~~~~~~~~~
@@ -46,6 +50,8 @@
     "EnumValue",
     "EnumName",
     "EnumNameList",
+    "AppendEnumValue",
+    "AppendEnumName",
     "DateAction",
     "TimeAction",
     "DateTimeAction",
@@ -59,15 +65,15 @@ class KeyValueAction(Action):
 
     Example of use::
 
+        @app.command
+        def my_command(options: Mapping[str, str]):
+            print(options)
+
         @app.command
         @argument("--option", action=KeyValueAction)
         def my_command(args: Namespace):
             print(args.option)
 
-        @app.command
-        def my_command(options: Mapping[str, str]):
-            print(options)
-
     From CLI::
 
         > my_app m_command --option a=foo --option b=bar
@@ -159,7 +165,7 @@ def to_enum(self, value):
 class EnumValue(_EnumAction):
     """
     Action to use an Enum as the type of an argument. In this mode the Enum is
-    reference by value.
+    referenced by value.
 
     The choices are automatically generated for help.
 
@@ -194,7 +200,7 @@ def to_enum(self, value):
 class EnumName(_EnumAction):
     """
     Action to use an Enum as the type of an argument. In this mode the Enum is
-    reference by name.
+    referenced by name.
 
     The choices are automatically generated for help.
 
@@ -226,10 +232,53 @@ def to_enum(self, value):
         return self._enum[value]
 
 
-class EnumNameList(EnumName):
+def _copy_items(items):
     """
-    Action to use an Enum as the type of an argument. In this mode the Enum is
-    reference by name and appended to a list.
+    Extracted from argparse
+    """
+    if items is None:
+        return []
+
+    # The copy module is used only in the 'append' and 'append_const'
+    # actions, and it is needed only when the default value isn't a list.
+    # Delay its import for speeding up the common case.
+    if isinstance(items, list):
+        return items[:]
+
+    import copy  # pylint: disable=import-outside-toplevel
+
+    return copy.copy(items)
+
+
+class _AppendEnumActionMixin(_EnumAction):
+    """
+    Mixin to support appending enum items
+    """
+
+    def __call__(self, parser, namespace, values, option_string=None):
+        items = getattr(namespace, self.dest, None)
+        items = _copy_items(items)
+        enum = self.to_enum(values)
+        items.append(enum)
+        setattr(namespace, self.dest, items)
+
+    def get_choices(self, choices: Union[Enum, Sequence[Enum]]):
+        """
+        Get choices from the enum
+        """
+        raise NotImplementedError  # pragma: no cover
+
+    def to_enum(self, value):
+        """
+        Get enum from the supplied value.
+        """
+        raise NotImplementedError  # pragma: no cover
+
+
+class AppendEnumValue(EnumValue, _AppendEnumActionMixin):
+    """
+    Action to use an Enum as the type of an argument and to accept multiple
+    enum values. In this mode the Enum is referenced by value.
 
     The choices are automatically generated for help.
 
@@ -241,28 +290,56 @@ class Colour(Enum):
             Blue = "blue"
 
         @app.command
-        @argument("--colour", type=Colour, action=EnumNameList)
+        @argument("--colours", type=Colour, action=AppendEnumValue)
         def my_command(args: Namespace):
             print(args.colour)
 
+        # Or using typing definition
+
         @app.command
-        def my_command(*, colour: Sequence[Colour]):
+        def my_command(*, colours: Sequence[Colour]):
+            print(colours)
+
+    From CLI::
+
+        > my_app m_command --colour red --colour blue
+        [Colour.Red, Colour.Blue]
+
+    .. versionadded:: 4.9
+
+    """
+
+
+class AppendEnumName(EnumName, _AppendEnumActionMixin):
+    """
+    Action to use an Enum as the type of an argument and to accept multiple
+    enum values. In this mode the Enum is referenced by name.
+
+    The choices are automatically generated for help.
+
+    Example of use::
+
+        class Colour(Enum):
+            Red = "red"
+            Green = "green"
+            Blue = "blue"
+
+        @app.command
+        @argument("--colours", type=Colour, action=AppendEnumName)
+        def my_command(args: Namespace):
             print(args.colour)
 
     From CLI::
 
-        > my_app m_command --colour Red --colour Green
-        [Colour.Red, Colour.Green]
+        > my_app m_command --colour Red --colour Blue
+        [Colour.Red, Colour.Blue]
 
-    .. versionadded:: 4.8.2
+    .. versionadded:: 4.9
 
     """
 
-    def __call__(self, parser, namespace, values, option_string=None):
-        enum = self.to_enum(values)
-        items = getattr(namespace, self.dest, None) or []
-        items.append(enum)
-        setattr(namespace, self.dest, items)
+
+EnumNameList = AppendEnumName
 
 
 class _DateTimeAction(Action):

src/pyapp/app/arguments.py

@@ -25,8 +25,8 @@
 from pyapp.compatability import async_run
 from pyapp.utils import cached_property
 
+from .argument_actions import AppendEnumName
 from .argument_actions import EnumName
-from .argument_actions import EnumNameList
 from .argument_actions import KeyValueAction
 from .argument_actions import TYPE_ACTIONS
 
@@ -233,13 +233,25 @@ def _handle_generics(  # pylint: disable=too-many-branches
                     "Only Optional[TYPE] or Union[TYPE, None] are supported"
                 )
 
+        elif name == "typing.Literal":
+            choices = type_.__args__
+            choice_type = type(choices[0])
+            if choice_type not in (str, int):
+                raise TypeError("Only str and int Literal types are supported")
+            # Ensure only a single type is supplied
+            if not all(isinstance(choice, choice_type) for choice in choices):
+                raise TypeError("All literal values must be the same type")
+
+            kwargs["choices"] = type_.__args__
+            return choice_type
+
         elif issubclass(origin, Tuple):
             kwargs["nargs"] = len(type_.__args__)
 
         elif issubclass(origin, Sequence):
             args = type_.__args__
             if len(args) == 1 and issubclass(args[0], Enum):
-                kwargs["action"] = EnumNameList
+                kwargs["action"] = AppendEnumName
             elif positional:
                 kwargs["nargs"] = "+"
             else:
@@ -339,7 +351,7 @@ def from_parameter(cls, name: str, parameter: inspect.Parameter) -> "Argument":
     def __init__(
         self,
         *name_or_flags,
-        action: str = None,
+        action: Union[str, Type[argparse.Action]] = None,
         nargs: Union[int, str] = None,
         const: Any = None,
         default: Any = EMPTY,

src/pyapp/checks/registry.py

@@ -11,6 +11,7 @@
 from typing import List
 from typing import NamedTuple
 from typing import Sequence
+from typing import TypeVar
 from typing import Union
 
 from pyapp import extensions
@@ -29,6 +30,7 @@ class Tags:
 
 
 Check = Callable[[Settings], Union[CheckMessage, Sequence[CheckMessage]]]
+_C = TypeVar("_C", bound=Callable[[Check], Check])
 
 
 class CheckResult(NamedTuple):
@@ -47,9 +49,11 @@ class CheckRegistry(List[Check]):
     Registry list for checks.
     """
 
-    def register(
-        self, check: Check = None, *tags
-    ):  # pylint: disable=keyword-arg-before-vararg
+    def register(  # pylint: disable=keyword-arg-before-vararg
+        self,
+        check: Union[Check, str] = None,
+        *tags: str,
+    ) -> Union[_C, Callable[[_C], _C]]:
         """
         Can be used as a function or a decorator. Register given function
         `func` labeled with given `tags`. The function should receive **kwargs

src/pyapp/conf/__init__.py

@@ -89,6 +89,12 @@
 
 .. autoclass:: HttpLoader
 
+Default settings
+================
+
+.. automodule:: pyapp.conf.base_settings
+    :members:
+
 """
 import logging
 import os

src/pyapp/conf/base_settings.py

@@ -1,9 +1,4 @@
-"""
-Default Settings
-~~~~~~~~~~~~~~~~
-
-.. auto
-"""
+"""Base settings used to initialise settings object."""
 from typing import Any
 from typing import Dict
 from typing import Sequence

src/pyapp/conf/loaders/__init__.py

@@ -20,9 +20,20 @@
 from pyapp.conf.loaders.file_loader import FileLoader
 from pyapp.conf.loaders.http_loader import HttpLoader
 from pyapp.exceptions import InvalidConfiguration
+from pyapp.typed_settings import SettingsDefType
 from yarl import URL
 
 
+def _settings_iterator(obj):
+    """Iterate settings from an object"""
+    for key in dir(obj):
+        value = getattr(obj, key)
+        if isinstance(value, SettingsDefType):
+            yield from getattr(value, "_settings", ())
+        elif key.isupper():
+            yield key, value
+
+
 class ModuleLoader(Loader):
     """
     Load configuration from an importable module.
@@ -57,7 +68,7 @@ def __iter__(self) -> Iterator[Tuple[str, Any]]:
         except ImportError as ex:
             raise InvalidConfiguration(f"Unable to load module: {self}\n{ex}") from ex
 
-        return ((k, getattr(mod, k)) for k in dir(mod) if k.isupper())
+        return _settings_iterator(mod)
 
     def __str__(self):
         return f"{self.scheme}:{self.module}"  # pylint: disable=no-member