appsettings2 1.3.7__tar.gz → 2.0.1__tar.gz

{appsettings2-1.3.7/src/appsettings2.egg-info → appsettings2-2.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: appsettings2
-Version: 1.3.7
+Version: 2.0.1
 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
@@ -31,10 +31,7 @@ Project-URL: Repository, https://github.com/wilson0x4d/appsettings2.git
 Keywords: appsettings,configuration
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -42,7 +39,10 @@ License-File: LICENSE
 Requires-Dist: pyyaml>=6.0.2
 Provides-Extra: dev
 Requires-Dist: coverage; extra == "dev"
+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.0; extra == "dev"
 Requires-Dist: twine; extra == "dev"
 Requires-Dist: types-PyYAML; extra == "dev"
@@ -69,9 +69,9 @@ from appsettings2 import *
 from appsettings2.providers import *
 
 config = ConfigurationBuilder()\
-    .addProvider(JsonConfigurationProvider(f'appsettings.json'))\
-    .addProvider(JsonConfigurationProvider(f'appsettings.Development.json', required=False))\
-    .addProvider(EnvironmentConfigurationProvider())\
+    .add_provider(JsonConfigurationProvider(f'appsettings.json'))\
+    .add_provider(JsonConfigurationProvider(f'appsettings.Development.json', required=False))\
+    .add_provider(EnvironmentConfigurationProvider())\
     .build()
 
 print(config)
@@ -140,7 +140,7 @@ class AppSettings:
     MaxBatchSize:int
 
 configuration = ConfigurationBuilder()\
-    .addProvider(JsonConfigurationProvider(json=json))
+    .add_provider(JsonConfigurationProvider(json=json))
     .build()
 
 settings = AppSettings()
@@ -184,7 +184,7 @@ print(d)
 
 ### Custom Provider Development
 
-You can implement custom Configuration Providers by subclassing `ConfigurationProvider` and implementing `populateConfiguration(...)`.
+You can implement custom Configuration Providers by subclassing `ConfigurationProvider` and implementing `populate_configuration(...)`.
 
 For a peek at the simplicity of provider implementation, this is `ConfigurationProvider`:
 
@@ -192,7 +192,7 @@ For a peek at the simplicity of provider implementation, this is `ConfigurationP
 class ConfigurationProvider(abstract):
 
     @abstractmethod
-    def populateConfiguration(self, configuration:Configuration) -> None:
+    def populate_configuration(self, configuration:Configuration) -> None:
         """The ConfigurationProvider will populate the provided Configuration instance."""
         pass
 ```
@@ -206,10 +206,10 @@ There are several helpers available which simplify loading configurations. Consi
 ```python
 import appsettings2
 
-config = appsettings2.getConfiguration()
+config = appsettings2.get_configuration()
 ```
 
-You can read more about `getConfiguration` in [the docs](https://appsettings2.readthedocs.io/en/latest/ref/helpers/getConfiguration.html).
+You can read more about `get_configuration` in [the docs](https://appsettings2.readthedocs.io/en/latest/ref/helpers/get_configuration.html).
 
 ## Contact
 

{appsettings2-1.3.7 → appsettings2-2.0.1}/README.md

@@ -19,9 +19,9 @@ from appsettings2 import *
 from appsettings2.providers import *
 
 config = ConfigurationBuilder()\
-    .addProvider(JsonConfigurationProvider(f'appsettings.json'))\
-    .addProvider(JsonConfigurationProvider(f'appsettings.Development.json', required=False))\
-    .addProvider(EnvironmentConfigurationProvider())\
+    .add_provider(JsonConfigurationProvider(f'appsettings.json'))\
+    .add_provider(JsonConfigurationProvider(f'appsettings.Development.json', required=False))\
+    .add_provider(EnvironmentConfigurationProvider())\
     .build()
 
 print(config)
@@ -90,7 +90,7 @@ class AppSettings:
     MaxBatchSize:int
 
 configuration = ConfigurationBuilder()\
-    .addProvider(JsonConfigurationProvider(json=json))
+    .add_provider(JsonConfigurationProvider(json=json))
     .build()
 
 settings = AppSettings()
@@ -134,7 +134,7 @@ print(d)
 
 ### Custom Provider Development
 
-You can implement custom Configuration Providers by subclassing `ConfigurationProvider` and implementing `populateConfiguration(...)`.
+You can implement custom Configuration Providers by subclassing `ConfigurationProvider` and implementing `populate_configuration(...)`.
 
 For a peek at the simplicity of provider implementation, this is `ConfigurationProvider`:
 
@@ -142,7 +142,7 @@ For a peek at the simplicity of provider implementation, this is `ConfigurationP
 class ConfigurationProvider(abstract):
 
     @abstractmethod
-    def populateConfiguration(self, configuration:Configuration) -> None:
+    def populate_configuration(self, configuration:Configuration) -> None:
         """The ConfigurationProvider will populate the provided Configuration instance."""
         pass
 ```
@@ -156,10 +156,10 @@ There are several helpers available which simplify loading configurations. Consi
 ```python
 import appsettings2
 
-config = appsettings2.getConfiguration()
+config = appsettings2.get_configuration()
 ```
 
-You can read more about `getConfiguration` in [the docs](https://appsettings2.readthedocs.io/en/latest/ref/helpers/getConfiguration.html).
+You can read more about `get_configuration` in [the docs](https://appsettings2.readthedocs.io/en/latest/ref/helpers/get_configuration.html).
 
 ## Contact
 

{appsettings2-1.3.7 → appsettings2-2.0.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "appsettings2"
-version = "1.3.7"
+version = "2.0.1"
 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 = [
@@ -11,10 +11,7 @@ license = {file = "LICENSE"}
 classifiers = [
     "Intended Audience :: Developers",
     "Operating System :: OS Independent",
-    "Programming Language :: Python :: 3.11",
-    "Programming Language :: Python :: 3.12",
-    "Programming Language :: Python :: 3.13",
-    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python",
     "Topic :: Software Development :: Libraries :: Python Modules"
 ]
 requires-python = ">=3.11"
@@ -25,7 +22,10 @@ dependencies = [
 [project.optional-dependencies]
 dev = [
     "coverage",
+    "flake8",
+    "flake8-pyproject",
     "mypy",
+    "pep8-naming",
     "punit (>=1.4.0)",
     "twine",
     "types-PyYAML"
@@ -50,3 +50,10 @@ exclude = [
 
 [tool.setuptools.package-data]
 "appsettings2" = ["py.typed"]
+
+[tool.flake8]
+max-line-length = 120
+ignore = ["D100","E501"]
+per-file-ignore = [
+    "tests/*.py:D012",
+]

{appsettings2-1.3.7 → appsettings2-2.0.1}/src/appsettings2/Configuration.py

@@ -6,48 +6,54 @@ import json
 import re
 import types
 import typing
-from typing import Any, TYPE_CHECKING
+from typing import Any, Iterator, TYPE_CHECKING
 import unicodedata
 
 from .ConfigurationException import ConfigurationException
 
 
 class Configuration:
-    """
-    The :py:class:`~appsettings2.Configuration` class is how applications access configuration data populated by :py:class:`~appsettings2.providers.ConfigurationProvider` objects. It exposes configuration data through dynamic object attributes as well as a dictionary-like interface.
-    """
+    """The :py:class:`~appsettings2.Configuration` class is how applications access configuration data populated by :py:class:`~appsettings2.providers.ConfigurationProvider` objects. It exposes configuration data through dynamic object attributes as well as a dictionary-like interface."""
 
-    __key_scrub_re:re.Pattern|None
-    __keys:dict[str, str]
-    __normalize:bool
+    __key_scrub_re: re.Pattern | None
+    __keys: dict[str, str]
+    __normalize: bool
 
-    def __init__(self, *, normalize:bool = False, scrubkeys:bool = False):
+    def __init__(self, normalize: bool = False, scrubkeys: bool = False) -> None:
         """
+        Initialize *Configuration* instance.
+
         :param normalize: Option indicating whether or not attribute names should be normalized to upper-case on the resulting :py:class:`~appsettings2.Configuration` object, defaults to False.
         :param scrubkeys: Option indicating whether or not attribute names should be scrubbed to be compatible with the Python lexer, defaults to False.
         """
         self.__keys = {}
         self.__logger = logging.getLogger('appsettings2')
         self.__normalize = normalize
-        self.__key_scrub_re = None if not scrubkeys else re.compile(r'[^A-Za-z0-9_]', re.IGNORECASE | re.UNICODE)
+        self.__key_scrub_re = None if not scrubkeys else re.compile(
+            r'[^A-Za-z0-9_]', re.IGNORECASE | re.UNICODE)
 
     if TYPE_CHECKING:
-        # This tells mypy that accessing any attribute returns 'Any'
-        def __getattr__(self, name: str) -> Any: ...
-        
+
+        def __getattr__(self, name: str) -> Any:
+            """Tell type checkers that accessing any attribute returns any type."""
+            ...
+
         # This tells mypy that setting any attribute is allowed
-        def __setattr__(self, name: str, value: Any) -> None: ...
+        def __setattr__(self, name: str, value: Any) -> None:
+            """Tell type checkers that setting any attribute to any value is allowed."""
+            ...
 
-    def __delitem__(self, key:str) -> None:
+    def __delitem__(self, key: str) -> None:
+        """Delete the specified configuration key."""
         key = key.upper()
         k = self.__keys.get(key)
         if k is not None:
             delattr(self, k)
             self.__keys.pop(key)
 
-    def __getitem__(self, key:str) -> Any:
+    def __getitem__(self, key: str) -> Any:
         """
-        Gets the configuration data associated with the specified `key`.
+        Get the configuration data associated with the specified configuration key.
 
         :param key: The configuration key to get data for. Supports `__` and `:` hierarchical delimiters.
         :return: The configuration data associated with `key`, otherwise raises `KeyError` if `key` was not found.
@@ -65,27 +71,31 @@ class Configuration:
                 o = o[part]
         return o
 
-    def __iter__(self):
+    def __iter__(self) -> Iterator[str]:
+        """Iterate configuration keys."""
         return iter(self.__keys.values())
 
     def __len__(self) -> int:
+        """Get the number of configuration keys."""
         return len(self.__keys)
 
-    def __recursiveBind(self, target:object, source:'Configuration|dict') -> Any:
+    def __recursive_bind(self, target: object, source: 'Configuration|dict') -> Any:
         if target is None:
             return None
         if hasattr(target, '__class__'):
-            targetTypeHints = typing.get_type_hints(getattr(target, '__class__'))
+            target_type_hints = typing.get_type_hints(
+                getattr(target, '__class__'))
         else:
-            targetTypeHints = typing.get_type_hints(target)
-        names = set(dir(target) | targetTypeHints.keys())
+            target_type_hints = typing.get_type_hints(target)
+        names = set(dir(target) | target_type_hints.keys())
         for aname in names:
             if aname.startswith('_'):
                 continue
-            lval = None if not hasattr(target, aname) else getattr(target, aname)
+            lval = None if not hasattr(
+                target, aname) else getattr(target, aname)
             if isinstance(lval, types.FunctionType) or isinstance(lval, types.MethodType):
                 continue
-            ahint = targetTypeHints.get(aname)
+            ahint = target_type_hints.get(aname)
             rval = source.get(aname)
             if ahint is None:
                 # attr has no type hints, attempt to treat as a property
@@ -95,7 +105,8 @@ class Configuration:
                         lval = getattr(target, aname)
                     except AttributeError:
                         lval = None
-                        self.__logger.debug(f'Failed to bind {aname}', exc_info=True)
+                        self.__logger.debug(
+                            f'Failed to bind {aname}', exc_info=True)
                 if (not hasattr(prop, 'fset') or getattr(prop, 'fset') is None):
                     # NOTE: lval is not settable
                     if rval is None:
@@ -107,7 +118,8 @@ class Configuration:
                             continue
                         elif not (issubclass(type(lval), list) and issubclass(type(rval), list)):
                             # non-list values cannot be merged
-                            raise Exception(f'Cannot bind `None` to attribute `{aname}`')
+                            raise Exception(
+                                f'Cannot bind `None` to attribute `{aname}`')
                 phints = typing.get_type_hints(getattr(prop, 'fget'))
                 if phints is None or (not issubclass(type(phints), dict)):
                     # NOTE: can't get hints from getter, can't bind
@@ -132,60 +144,64 @@ class Configuration:
                     if lval is None:
                         lval = ahint()
                         setattr(target, aname, lval)
-                    self.__recursiveBind(lval, rval)
+                    self.__recursive_bind(lval, rval)
             elif typing.get_origin(ahint) is list:
-                elementType = ahint.__args__[0]
+                element_type = ahint.__args__[0]
                 if lval is None:
                     lval = ahint()
                     setattr(target, aname, lval)
                 for e in rval:
                     lval.append(
-                        self.__recursiveBindType(elementType, e)
+                        self.__recursive_bind_type(element_type, e)
                     )
             else:
                 setattr(target, aname, rval)
         return target
 
-    def __recursiveBindType(self, elementType:type, source:Any) -> Any:
-        if isinstance(source, elementType):
+    def __recursive_bind_type(self, element_type: type, source: Any) -> Any:
+        if isinstance(source, element_type):
             return source
-        elif elementType is float:
+        elif element_type is float:
             return float(source)
-        elif elementType is int:
+        elif element_type is int:
             return int(source)
-        elif elementType is str:
+        elif element_type is str:
             return str(source)
         elif isinstance(source, Configuration | dict):
-            v = elementType()
-            return self.__recursiveBind(v, source)       
+            v = element_type()
+            return self.__recursive_bind(v, source)
         else:
-            raise ConfigurationException(f'Recursive bind to type `{elementType}` from `{type(source)}` is not supported.')
+            raise ConfigurationException(
+                f'Recursive bind to type `{element_type}` from `{type(source)}` is not supported.')
 
-    def __scrub_key(self, key:str) -> str:
+    def __scrub_key(self, key: str) -> str:
         """Scrubs a key for use as an attribute/identifier according to the Python lexer/standard."""
         key = key.replace(':', '__').replace('.', '_')
         return key if self.__key_scrub_re is None else self.__key_scrub_re.sub(
-                self.__scrub_uc,
-                unicodedata.normalize(
-                    'NFKC',
-                    key))
+            self.__scrub_uc,
+            unicodedata.normalize(
+                'NFKC',
+                key))
 
-    def __scrub_uc(self, m:re.Match) -> str:
+    def __scrub_uc(self, m: re.Match) -> str:
         match unicodedata.category(m[0]):
-            case 'Lu' | 'Ll' | 'Lt' | 'Lm' | 'Lo' | 'Nl' | 'Mn' | 'Mc' | 'Nd' | 'Pc' :
+            case 'Lu' | 'Ll' | 'Lt' | 'Lm' | 'Lo' | 'Nl' | 'Mn' | 'Mc' | 'Nd' | 'Pc':
                 return m[0]
             case _:
                 return '_'
 
-    def __setitem__(self, key:str, value:Any) -> None:
+    def __setitem__(self, key: str, value: Any) -> None:
+        """Set configuration key to specified *value*."""
         self.set(key, value)
 
     def __str__(self) -> str:
-        return json.dumps(self.toDictionary())
+        """Render the configuration as a JSON string."""
+        return json.dumps(self.to_dict(), indent=None, ensure_ascii=False)
 
-    def bind(self, target:object, key:str|None = None) -> Any:
+    def bind(self, target: object, key: str | None = None) -> Any:
         """
         Binds the configuration values into the target object.
+
         Can optionally specify a configuration key to bind from.
 
         :param target: The object to bind configuration data into.
@@ -195,43 +211,50 @@ class Configuration:
         if target is None:
             raise ConfigurationException('Missing required argument: target')
         if key is None:
-            return self.__recursiveBind(target, self)
+            return self.__recursive_bind(target, self)
         else:
             source = self.get(key)
             if source is not None:
-                sourceType = type(source)
-                if sourceType is Configuration or sourceType is dict:
-                    return self.__recursiveBind(target, source)
+                source_type = type(source)
+                if source_type is Configuration or source_type is dict:
+                    return self.__recursive_bind(target, source)
                 else:
-                    raise ConfigurationException(f'Bind of source type `{type(source)}` is not supported.')
+                    raise ConfigurationException(
+                        f'Bind of source type `{type(source)}` is not supported.')
             return target
 
     def clear(self) -> None:
+        """Clear all configuration data."""
         while len(self.__keys) > 0:
             t = self.__keys.popitem()
             delattr(self, t[1])
 
     @staticmethod
-    def fromDictionary(source:dict, *, normalize:bool = False, scrubkeys:bool = False) -> 'Configuration':
+    def from_dict(source: dict, normalize: bool = False, scrubkeys: bool = False) -> 'Configuration':
         """
-        Constructs a :py:class:`~appsettings2.Configuration` instance from the supplied dictionary `source`.
+        Construct a :py:class:`~appsettings2.Configuration` instance from the supplied dictionary `source`.
 
         :param source: The dictionary object to populate from.
         :param normalize: Option indicating whether or not attribute names should be normalized to upper-case on the resulting :py:class:`~appsettings2.Configuration` object, defaults to False.
         :param scrubkeys: Option indicating whether or not attribute names should be scrubbed to be compatible with the Python lexer, defaults to False.
         :return: A :py:class:`~appsettings2.Configuration` object derived from the `source` parameter.
         """
-        config:Configuration = Configuration(normalize=normalize, scrubkeys=scrubkeys)
+        config: Configuration = Configuration(
+            normalize=normalize, scrubkeys=scrubkeys)
         for kvp in source.items():
             v = kvp[1]
             if issubclass(type(v), dict):
-                v = Configuration.fromDictionary(v, normalize=normalize, scrubkeys=scrubkeys)
+                v = Configuration.from_dict(
+                    v, normalize=normalize, scrubkeys=scrubkeys)
             config.set(kvp[0], v)
         return config
 
-    def get(self, key:str, default:Any = None) -> Any:
+    fromDictionary = from_dict  # noqa: N815
+    """⚠️ DEPRECATED: use ``from_dict(...)`` instead."""
+
+    def get(self, key: str, default: Any = None) -> Any:
         """
-        Gets the configuration data associated with the specified `key`.
+        Get the configuration data associated with the specified `key`.
 
         :param key: The configuration key to get data for. Supports `__` and `:` hierarchical delimiters.
         :param default: The value to be returned if `key` does not exist, defaults to None
@@ -250,10 +273,12 @@ class Configuration:
                 o = o.get(part, default)
         return o
 
-    def has_key(self, key:str) -> bool:
+    def has_key(self, key: str) -> bool:
+        """Check for a specific configuration key."""
         return self.__keys.get(key.upper()) is not None
 
-    def items(self) -> list[tuple[str,Any]]:
+    def items(self) -> list[tuple[str, Any]]:
+        """Get all key-value pairs as individal ``tuple`` items."""
         it = []
         for k in self.keys():
             v = self.get(k)
@@ -261,19 +286,21 @@ class Configuration:
         return it
 
     def keys(self) -> list[str]:
+        """Get a list of all configuration keys."""
         return list(self.__keys.values())
 
-    def pop(self, key:str) -> Any:
+    def pop(self, key: str) -> Any:
+        """Delete a specific configuration key."""
         value = self[key]
         del self[key]
         return value
 
-    def set(self, key:str, value:Any) -> None:
+    def set(self, key: str, value: Any) -> None:
         """
-        Sets the configuration data for the specified `key`.
+        Set the configuration value for a configuration key.
 
-        :param key: The key to associate the configuration data.
-        :param value: The configuration data so be associated with `key`.
+        :param key: The *key* to associate the configuration *value*.
+        :param value: The *value* to be associated with the configuration *key*.
         """
         if self.__normalize:
             key = key.upper()
@@ -283,7 +310,8 @@ class Configuration:
             if o == self:
                 k = self.__keys.get(parts[i].upper())
                 if k is None:
-                    c = Configuration(normalize=self.__normalize, scrubkeys=(None != self.__key_scrub_re))
+                    c = Configuration(normalize=self.__normalize, scrubkeys=(
+                        self.__key_scrub_re is None))
                     setattr(o, self.__scrub_key(parts[i]), c)
                     self.__keys[parts[i].upper()] = parts[i]
                     o = c
@@ -291,19 +319,22 @@ class Configuration:
                     o = getattr(self, self.__scrub_key(k))
             else:
                 if not o.has_key(parts[i]):
-                    c = Configuration(normalize=self.__normalize, scrubkeys=(None != self.__key_scrub_re))
+                    c = Configuration(normalize=self.__normalize, scrubkeys=(
+                        self.__key_scrub_re is None))
                     o.set(parts[i], c)
                     o = c
                 else:
                     o = o.get(parts[i])
         vtype = type(value)
         if issubclass(vtype, dict):
-            value = Configuration.fromDictionary(value, normalize=self.__normalize, scrubkeys=self.__key_scrub_re is not None)
+            value = Configuration.from_dict(
+                value, normalize=self.__normalize, scrubkeys=self.__key_scrub_re is not None)
         elif issubclass(vtype, list):
-            l = []
+            l: list[Any] = list[Any]()
             for e in value:
                 if issubclass(type(e), dict):
-                    l.append(Configuration.fromDictionary(e, normalize=self.__normalize, scrubkeys=self.__key_scrub_re is not None))
+                    l.append(Configuration.from_dict(
+                        e, normalize=self.__normalize, scrubkeys=self.__key_scrub_re is not None))
                 else:
                     l.append(e)
             value = l
@@ -318,13 +349,13 @@ class Configuration:
         else:
             o.set(key, value)
 
-    def toDictionary(self) -> dict[str,Any]:
+    def to_dict(self) -> dict[str, Any]:
         """
-        Creates a dictionary from the `Configuration` object.
+        Create a dictionary from the `Configuration` object.
 
         :return: A dictionary containing all keys and their associated values, in a structure that mimics the structure if the data contained within the `Configuration` object.
         """
-        result = dict[str,Any]()
+        result = dict[str, Any]()
         for k in self.__keys.values():
             v = getattr(self, self.__scrub_key(k))
             if isinstance(v, Configuration):
@@ -341,7 +372,11 @@ class Configuration:
                 result[k] = v
         return result
 
+    toDictionary = to_dict  # noqa: N815
+    """⚠️ DEPRECATED: use ``to_dict(...)`` instead."""
+
     def values(self) -> list[Any]:
+        """Get a list of all configuration values."""
         values = []
         for k in self.__keys.values():
             v = getattr(self, self.__scrub_key(k))