appsettings2 2.0.7__tar.gz → 2.0.10__tar.gz

{appsettings2-2.0.7/src/appsettings2.egg-info → appsettings2-2.0.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: appsettings2
-Version: 2.0.7
+Version: 2.0.10
 Summary: Unifies configuration sources into a Configuration object that can be bound to complex types, or accessed directly for configuration data.
 Author-email: Shaun Wilson <mrshaunwilson@msn.com>
 License: MIT License
@@ -42,7 +42,7 @@ Requires-Dist: flake8; extra == "dev"
 Requires-Dist: flake8-pyproject; extra == "dev"
 Requires-Dist: mypy; extra == "dev"
 Requires-Dist: pep8-naming; extra == "dev"
-Requires-Dist: punit>=1.4.9; extra == "dev"
+Requires-Dist: punit>=1.10.8; extra == "dev"
 Requires-Dist: twine; extra == "dev"
 Requires-Dist: types-PyYAML; extra == "dev"
 Dynamic: license-file

{appsettings2-2.0.7 → appsettings2-2.0.10}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "appsettings2"
-version = "2.0.7"
+version = "2.0.10"
 description = "Unifies configuration sources into a Configuration object that can be bound to complex types, or accessed directly for configuration data."
 keywords = ["appsettings", "configuration"]
 authors = [
@@ -25,7 +25,7 @@ dev = [
     "flake8-pyproject",
     "mypy",
     "pep8-naming",
-    "punit (>=1.4.9)",
+    "punit (>=1.10.8)",
     "twine",
     "types-PyYAML"
 ]

{appsettings2-2.0.7 → appsettings2-2.0.10}/src/appsettings2/Configuration.py

@@ -86,6 +86,8 @@ class Configuration:
     def __deunionize(self, t: type) -> type:
         if get_origin(t) is Union:
             t = [e for e in get_args(t) if e is not NoneType][0]
+        elif get_origin(t) is types.UnionType:
+            t = [e for e in get_args(t) if e is not NoneType][0]
         return t
 
     def __recursive_bind(self, target: object, source: Configuration | dict[str, Any]) -> Any:
@@ -97,6 +99,14 @@ class Configuration:
             )
         else:
             target_type_hints = get_type_hints(target)
+
+        # build scrubbed/normalized key lookup (for matching)
+        norm_source: bool | None = None
+        key_scrub_re_cfg: re.Pattern[str] | None = None
+        if isinstance(source, Configuration):
+            norm_source = source._Configuration__normalize
+            key_scrub_re_cfg = source._Configuration__key_scrub_re
+
         names = set(dir(target) | target_type_hints.keys())
         for aname in names:
             if aname.startswith('_'):
@@ -107,6 +117,20 @@ class Configuration:
                 continue
             ahint = target_type_hints.get(aname)
             rval = source.get(aname)
+            # scrub/normalize-aware; look up using transformed keys
+            if rval is None and norm_source is not None:
+                raw_src_key = aname.replace(':', '__')
+                for cfg_key in source.keys():  # type: ignore[union-attr]
+                    raw = cfg_key.replace('.', '_')
+                    candidate = raw.upper() if norm_source else raw
+                    scrubbed = candidate if key_scrub_re_cfg is None \
+                        else key_scrub_re_cfg.sub(
+                            lambda m: '_' if unicodedata.category(m[0]) not in ('Lu', 'Ll', 'Lt', 'Lm', 'Lo', 'Nl', 'Mn', 'Mc', 'Nd', 'Pc') else m[0],
+                            candidate)
+                    compare = scrubbed.replace('-', '_')
+                    if compare == raw_src_key or compare.upper() == raw_src_key.upper():
+                        rval = source.get(cfg_key)  # type: ignore[union-attr]
+                        break
             if ahint is None:
                 # attr has no type hints, attempt to treat as a property
                 prop = getattr(type(target), aname)
@@ -156,7 +180,37 @@ class Configuration:
                                 lval[dk] = self.__recursive_bind_type(value_type, dv)
                             setattr(target, aname, lval)
                         continue
+                # Union/Optional types when rval missing but there's source data?
+                if get_origin(ahint) is Union or get_origin(ahint) is types.UnionType \
+                        or (isinstance(ahint, type) and hasattr(ahint, '__origin__')):
+                    unwrapped = self.__deunionize(ahint)
+                    if unwrapped not in (str, int, float, bool, NoneType):
+                        # source key overlaps with attr names?
+                        src_key_overlap = False
+                        for cfg_key in source.keys():  # type: ignore[union-attr]
+                            raw_src_key = cfg_key.replace('.', '_')
+                            candidate = raw_src_key.upper() if norm_source else raw_src_key
+                            scrubbed = candidate if key_scrub_re_cfg is None \
+                                else key_scrub_re_cfg.sub(
+                                    lambda m: '_' if unicodedata.category(m[0]) not in ('Lu', 'Ll', 'Lt', 'Lm', 'Lo', 'Nl', 'Mn', 'Mc', 'Nd', 'Pc') else m[0],
+                                    candidate)
+                            compare = scrubbed.replace('-', '_').replace('_', '')
+                            for other_attr in names:
+                                if not other_attr.startswith('_'):
+                                    okey = other_attr.replace(':', '__')
+                                    if compare == okey or compare.upper() == okey.upper():
+                                        src_key_overlap = True
+                                        break
+                            if src_key_overlap:
+                                break
+                        if isinstance(source, Configuration) and source.keys() and not src_key_overlap:  # type: ignore[union-attr]
+                            lval = unwrapped()
+                            setattr(target, aname, lval)
+                            self.__recursive_bind(lval, source)
+                            continue
                 setattr(target, aname, None)
+            elif ahint is bool:
+                setattr(target, aname, bool(rval))
             elif ahint is float:
                 setattr(target, aname, float(rval))
             elif ahint is int:
@@ -174,6 +228,28 @@ class Configuration:
                         for dk, dv in rval.items():
                             lval[dk] = self.__recursive_bind_type(value_type, dv)
                         setattr(target, aname, lval)
+                elif (
+                    get_origin(ahint) is Union
+                    or get_origin(ahint) is types.UnionType
+                    or (isinstance(ahint, type) and hasattr(ahint, '__origin__'))
+                ):
+                    # Handle Optional/Union types — unwrap before instantiating
+                    unwrapped = self.__deunionize(ahint)
+                    if get_origin(unwrapped) is dict:
+                        value_type = get_args(unwrapped)[1]
+                        if value_type in (str, int, float, bool, type(None)):
+                            lval = rval.to_dict()
+                            setattr(target, aname, lval)
+                        else:
+                            lval = dict[str, Any]()
+                            for dk, dv in rval.items():
+                                lval[dk] = self.__recursive_bind_type(value_type, dv)
+                            setattr(target, aname, lval)
+                    else:
+                        if lval is None:
+                            lval = unwrapped()
+                            setattr(target, aname, lval)
+                        self.__recursive_bind(lval, rval)
                 else:
                     if lval is None:
                         ahint = self.__deunionize(ahint)
@@ -262,12 +338,66 @@ class Configuration:
             source = self.get(key)
             if source is not None:
                 source_type = type(source)
-                if source_type is Configuration or source_type is dict:
+                if source_type in (Configuration, dict):
                     return self.__recursive_bind(target, source)
+                elif source_type is list:
+                    return self.__bind_list_source(target, key, source)
                 else:
-                    raise ConfigurationException(
-                        f'Bind of source type `{type(source)}` is not supported.')
+                    # Scalar source: convert to matching typed attribute(s) on target
+                    return self.__bind_scalar_to_target(target, key, source)
+            else:
+                return target
+
+    def __bind_list_source(self, target: object, key: str, source: list[Any]) -> Any:
+        """Bind a Configuration- or dict-wrapped list source to *target*."""
+        if not hasattr(target, '__class__'):
             return target
+        hints = get_type_hints(type(target))
+        raw_key = self.__scrub_key(key.replace(':', '__'))
+        for attr_name, ahint in hints.items():
+            if raw_key == self.__scrub_key(attr_name) or key.upper() == attr_name.upper():
+                element_type = ahint.__args__[0] if get_origin(ahint) is list else None
+                if element_type is not None and source:
+                    lval = []
+                    for e in source:
+                        lval.append(self.__recursive_bind_type(element_type, e))
+                    setattr(target, attr_name, lval)
+                    return target
+        # taking object/untyped attr from normalized
+        for attr_name, ahint in hints.items():
+            if raw_key == self.__scrub_key(attr_name) or key.upper() == attr_name.upper():
+                if ahint is object:
+                    setattr(target, attr_name, source)
+                    return target
+        return target
+
+    def __bind_scalar_to_target(self, target: object, key: str, value: Any) -> Any:
+        """Bind a scalar config value to the typed attribute on *target* matching the key."""
+        if not hasattr(target, '__class__'):
+            return target
+        hints = get_type_hints(type(target))
+        # Normalize / scrub exactly as :py:meth:`set` does so we can match back.
+        raw_key = self.__scrub_key(key.replace(':', '__'))
+        for attr_name, ahint in hints.items():
+            if raw_key == self.__scrub_key(attr_name):
+                converted = self.__convert_to_type(value, ahint)
+                setattr(target, attr_name, converted)
+        return target
+
+    @staticmethod
+    def __convert_to_type(value: Any, target_type: type) -> Any:
+        """Convert *value* to *target_type* using primitive coercion rules."""
+        if target_type is float:
+            return float(value)
+        elif target_type is int:
+            return int(value)
+        elif target_type is str:
+            return str(value)
+        elif target_type is bool:
+            return bool(value)
+        else:
+            # Complex type or Any — nothing we can do for a scalar source
+            return value
 
     def clear(self) -> None:
         """Clear all configuration data."""

{appsettings2-2.0.7 → appsettings2-2.0.10}/src/appsettings2/ConfigurationBuilder.py

@@ -65,13 +65,14 @@ class ConfigurationBuilder:
     addCommandLine = add_command_line
     """⚠️ DEPRECATED: use ``add_command_line(...)`` instead."""
  
-    def add_environment(self) -> 'ConfigurationBuilder':
+    def add_environment(self, required_prefix: str | None = None) -> 'ConfigurationBuilder':
         """
         Add a :py:class:`~appsettings2.providers.EnvironmentConfigurationProvider`.
 
+        :param required_prefix: Optional prefix used to filter which environment variables are included. Only variables whose names start with this prefix (followed by ``_`` or ``__``) will be loaded. When ``None``, all environment variables are included. Defaults to None.
         :return: Returns :py:class:`~appsettings2.ConfigurationBuilder` for method chaining.
         """
-        return self.add_provider(EnvironmentConfigurationProvider())
+        return self.add_provider(EnvironmentConfigurationProvider(required_prefix=required_prefix))
 
     addEnvironment = add_environment
     """⚠️ DEPRECATED: use ``add_environment(...)`` instead."""

{appsettings2-2.0.7 → appsettings2-2.0.10}/src/appsettings2/__init__.py

@@ -10,8 +10,8 @@ from . import helpers
 from . import providers
 
 
-__version__ = '2.0.7'
-__commit__ = '62b357b'
+__version__ = '2.0.10'
+__commit__ = 'fe8eec3'
 __all__ = [
     '__version__', '__commit__',
     'Configuration',

{appsettings2-2.0.7 → appsettings2-2.0.10}/src/appsettings2/helpers.py

@@ -8,7 +8,17 @@ from .Configuration import Configuration
 from .ConfigurationBuilder import ConfigurationBuilder
 
 
-def get_configuration(basename: str | pathlib.PosixPath | pathlib.Path = 'appsettings', json: bool = True, toml: bool = True, yaml: bool = True, cli: bool = True, environment: bool = True, variations: Optional[list[str | None]] = ['', 'prod', 'production', 'stage', 'staging', 'qa', 'dev', 'development', 'local']) -> Configuration:
+def get_configuration(
+    basename: str | pathlib.PosixPath | pathlib.Path = 'appsettings',
+    *,
+    json: bool = True,
+    toml: bool = True,
+    yaml: bool = True,
+    cli: bool = True,
+    environment: bool = True,
+    variations: Optional[list[str | None]] = ['', 'prod', 'production', 'stage', 'staging', 'qa', 'dev', 'development', 'local'],
+    env_prefix: str | None = None
+) -> Configuration:
     """
     Get a ``Configuration`` instance by loading from a set of well-known providers and their variations.
 
@@ -19,6 +29,7 @@ def get_configuration(basename: str | pathlib.PosixPath | pathlib.Path = 'appset
     :param cli: ``True`` to load configuration from Command-Line, defaults to True
     :param environment: ``True`` to load configuration from process Environment, defaults to True
     :param variations: A set of variations to apply to use with file-based Configuration Providers, defaults to ['', 'prod', 'production', 'stage', 'staging', 'qa', 'dev', 'development', 'local']
+    :param env_prefix: (OPTIONAL) When specified, only env vars having the specified prefix are bound as configuration settings, the prefix is stripped from the resulting setting name.
     :return: An ``appsettings2.Configuration`` instance.
     """
     if type(basename) is pathlib.Path or type(basename) is pathlib.PosixPath:
@@ -36,7 +47,7 @@ def get_configuration(basename: str | pathlib.PosixPath | pathlib.Path = 'appset
     if cli:
         builder.add_command_line()
     if environment:
-        builder.add_environment()
+        builder.add_environment(required_prefix=env_prefix)
     return builder.build()
 
 

appsettings2-2.0.10/src/appsettings2/providers/EnvironmentConfigurationProvider.py

@@ -0,0 +1,43 @@
+# SPDX-FileCopyrightText: © 2025 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+import os
+from typing import Any
+
+from ..Configuration import Configuration
+from .ConfigurationProvider import ConfigurationProvider
+
+
+class EnvironmentConfigurationProvider(ConfigurationProvider):
+    """A ``ConfigurationProvider`` that populates configuration data from Environment variables."""
+
+    __required_prefix: str | None
+
+    def __init__(self, /, required_prefix: str | None = None, **kwargs: Any) -> None:
+        self.__required_prefix = required_prefix.upper() if required_prefix is not None else None
+
+    def populate_configuration(self, configuration: Configuration) -> None:
+        """
+        Populate the provided :py:class:`~appsettings2.Configuration` from environment variables.
+
+        Usage::
+
+            # All env vars become config keys:
+            provider = EnvironmentConfigurationProvider()
+            provider.populate_configuration(config)
+
+            # Only keys with a specific prefix, stripped in output:
+            provider = EnvironmentConfigurationProvider(required_prefix="APP_")
+            # APP_DATABASE_URL=postgres://...  →  config["DATABASE_URL"] == "postgres://..."
+            provider.populate_configuration(config)
+
+        When ``required_prefix`` is set, only keys starting with that prefix are included,
+        and the prefix is stripped from each key in the output configuration.
+        """
+        for k in os.environ:
+            key = (
+                k
+                if self.__required_prefix is None
+                else k[len(self.__required_prefix):]
+            )
+            configuration.set(key, os.environ[k])

{appsettings2-2.0.7 → appsettings2-2.0.10/src/appsettings2.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: appsettings2
-Version: 2.0.7
+Version: 2.0.10
 Summary: Unifies configuration sources into a Configuration object that can be bound to complex types, or accessed directly for configuration data.
 Author-email: Shaun Wilson <mrshaunwilson@msn.com>
 License: MIT License
@@ -42,7 +42,7 @@ Requires-Dist: flake8; extra == "dev"
 Requires-Dist: flake8-pyproject; extra == "dev"
 Requires-Dist: mypy; extra == "dev"
 Requires-Dist: pep8-naming; extra == "dev"
-Requires-Dist: punit>=1.4.9; extra == "dev"
+Requires-Dist: punit>=1.10.8; extra == "dev"
 Requires-Dist: twine; extra == "dev"
 Requires-Dist: types-PyYAML; extra == "dev"
 Dynamic: license-file

{appsettings2-2.0.7 → appsettings2-2.0.10}/src/appsettings2.egg-info/requires.txt

@@ -6,6 +6,6 @@ flake8
 flake8-pyproject
 mypy
 pep8-naming
-punit>=1.4.9
+punit>=1.10.8
 twine
 types-PyYAML

appsettings2-2.0.7/src/appsettings2/providers/EnvironmentConfigurationProvider.py

@@ -1,14 +0,0 @@
-# SPDX-FileCopyrightText: © 2025 Shaun Wilson
-# SPDX-License-Identifier: MIT
-
-from .ConfigurationProvider import ConfigurationProvider
-from ..Configuration import Configuration
-import os
-
-
-class EnvironmentConfigurationProvider(ConfigurationProvider):
-    """A ``ConfigurationProvider`` that populates configuration data from Environment variables."""
-
-    def populate_configuration(self, configuration: Configuration) -> None:  # noqa: D102
-        for k in os.environ:
-            configuration.set(k, os.environ[k])