appsettings2 0.0.1__tar.gz

appsettings2-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Shaun Wilson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

appsettings2-0.0.1/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.1
+Name: appsettings2
+Version: 0.0.1
+Summary: A python library that unifies configuration sources into a Configuration object that can be bound to complex types, or accessed directly for configuration data.
+License: MIT
+Author: Shaun Wilson
+Author-email: mrshaunwilson@msn.com
+Requires-Python: >=3.11,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
+Project-URL: documentation, https://github.com/wilson0x4d/appsettings2/README.md
+Project-URL: homepage, https://github.com/wilson0x4d/appsettings2
+Project-URL: repository, https://github.com/wilson0x4d/appsettings2.git
+Description-Content-Type: text/markdown
+
+# `appsettings2`
+
+A python library that unifies configuration sources into a Configuration object that can be bound to complex types, or accessed directly for configuration data.
+
+## Why?
+
+Because I write a lot of containerized applications where I typically supply configuration settings using a combination of Configuration Files and Environment Variables.
+
+When I debug those applications I often need to override Confguration using Command-Line Arguments, Configuration Files, Environment Variables, or a combination thereof.
+
+## Usage
+
+Construct a `ConfigurationBuilder` instance, add one or more `ConfigurationProvider` instances to it, and then use it to build a `Configuration` object containing your unified configuration data.
+
+```python
+from appsettings2 import *
+from appsettings2.providers import *
+
+def get_configuration() -> Configuration:
+    return ConfigurationBuilder()\
+        .addProvider(JsonConfigurationProvider(f'appsettings.json'))\
+        .addProvider(JsonConfigurationProvider(f'appsettings.Development.json', required=False))\
+        .addProvider(EnvironmentConfigurationProvider())\
+        .build()
+```
+
+In the above example two JSON Configuration Providers are added to the builder. The first will fail if "appsettings.json" is not found, the second will succeed whether or not the "appsettings.Development.json" exists (because `required=False`). This allows for an optional development configuration to exist on development workstations without requiring a code change.
+
+A third Configuration Provider is also added, an `EnvironmentConfigurationProvider`, which allows configuration to be loaded from Environment Variables.
+
+The order of providers determines precedence of configuration data. Providers added last will take precedence over providers added first. Values which are not provided by later registrations will not override values provided by earlier registrations.
+
+Given the example above, this means that configuration data provided via Environment Variables will override configuration data provided via JSON files.
+
+## Accssing Configuration Data
+
+There are two methods of directly accessing Configuration data directly. The first is by using first-class attributes in python, and the second is by using a `get(...)` method. 
+
+Consider the following code which demonstrates both methods, where all three of these statements are equivalent:
+
+```python
+value = configuration.ConnectionStrings.SampleDb
+value = configuration.get('ConnectionStrings:SampleDb')
+value = configuration.get('ConnectionStrings__SampleDb')
+```
+
+When accessing hierarchical data you can use a double-underscore delimiter or a colon delimiter, they are equivalent. Devs and Ops from different walks will likely prefer one form over the other, so both are supported.
+
+## Binding to Configuration Data
+
+It's also possible to bind configuration data to complex types. While some of the implementation is currently naive, it should work well for the vast majority of use-cases. If you find your particular edge case does not work well please reach out to me and I will work with you to implement a sensible solution.  Consider the following Python code:
+
+```python
+json = """{
+  "ConnectionStrings": {
+    "SampleDb": "my_cxn_string"
+  },
+  "EnableSwagger": true,
+  "MaxBatchSize": 100
+}"""
+
+class ConnStrs:
+    """An ugly class name to demonstrate the class name does not matter."""
+    SampleDb:str = None
+
+class AppSettings:
+    ConnectionStrings:ConnStrs = None
+    EnableSwagger:bool = None
+    MaxBatchSize:int = None
+
+configuration = ConfigurationBuilder()\
+    .addProvider(JsonConfigurationProvider(json=json))
+    .build()
+
+settings = AppSettings()
+configuration.bind(settings)
+```
+
+The resulting `settings` object will contain all of the configuration data properly typed according to type hints.
+
+It is also possible to bind to a subset of a configuration, building upon the above, consider the following:
+
+```python
+connectionStrings = configuration.bind(ConnectionStrings(), 'ConnectionStrings')
+```
+
+### Projecting Configuration Data as a Dictionary
+
+Laslty, as a convenience item you can materialize a `Configuration` instance as a Dictionary. This is primarily included as a debugging aid, but, if you have some chunk of code that can consume a dictionary but can't consume a Python object (it happens) then you can get at a dictionary as follows:
+
+```python
+config:Configuration = builder.build()
+my_dict = config.toDictionary()
+print(my_dict)
+```
+
+## Providers
+
+### Command-Line
+
+The `CommandLineConfigurationProvider` allows configuration data to be provided via command-line interface. This provider will process variables in the following forms as key-value pairs:
+
+```
+--ConnectionStrings__SampleDb 'my_connection_string'
+```
+
+```
+'ConnectionStrings__SampleDb=my_connection_string'
+```
+
+```
+--ConnectionStrings__SampleDb=my_connection_string
+```
+
+All three of these forms result in a configuration object with the following state (represented as JSON):
+
+```json
+{
+    "ConnectionStrings" : {
+        "SampleDb": "my_connection_string"
+    }
+}
+```
+
+Take note that the leading dashes are stripped.
+
+This double-underscore convention is a convention borrowed from other platforms/frameworks.
+
+It's also possible to use a colon in lieu of a double_underscore, but this may have unintended side-effects depending on the shell or platform being used:
+
+```
+'ConnectionStrings:SampleDb=my_connection_string'
+```
+
+This provider was implemented in a way that it does not interfere with libraries such as `argparse`, and should work as expected with a well-formed command-line interface. 
+
+### Environment Variables
+
+The `EnvironmentConfigurationProvider` consumes environment variables as key-value pairs. For example, consider these `bash` exports:
+
+```bash
+export ConnectionStrings__SampleDb=my_cxn_string
+export ConnectionStrings__AnotherDb=another_cxn_string
+```
+
+The above will resule in a Configuration object with the following state (represented as JSON):
+
+```json
+{
+    "ConnectionStrings": {
+        "SampleDb": "my_cxn_string",
+        "AnotherDb": "another_cxn_string"
+    }
+}
+```
+
+### JSON
+
+The `JsonConfigurationProvider` class allows you to load configuration data from a JSON file, JSON string, or JSON stream. Consider the following JSON:
+
+```json
+{
+    "Logging": {
+        "Default": "Debug"
+    },
+    "ConnectionStrings": {
+        "SampleDb": "my_cxn_string"
+    },
+}
+```
+
+When loaded using `JsonConfigurationProvider` the resulting `Configuration` object will have attribute names and a structure which matches the JSON, consider the following Python code (where "example.json" contains the above JSON):
+
+```python
+from appsettings2 import *
+from appsettings2.providers import *
+
+config = ConfigurationBuilder(normalize=True)\
+    .addProvider(JsonConfigurationProvider('example.json'))\
+    .build()
+
+print(config.ConnectionStrings.SampleDb)
+```
+Outputs: `my_cxn_string` (as expected.)
+
+### TOML
+
+The `TomlConfigurationProvider` should be functionally identical to the JSON provider, with the obvious difference that it loads Configuration data from a toml file.
+
+### YAML
+
+The `YamlConfigurationProvider` should be functionally identical to the JSON and TOML providers, with the obvious difference that it loads Configuration data from a yaml file.
+
+## A note on `normalize` parameters..
+
+`ConfigurationBuilder` accepts a parameter `normalize:bool` which defaults to `False` causing `bind()` to behave in a case-sensitive fashion.
+
+When set to `True` it causes the internal implementation of `Configuration` to normalize all configuration keys to uppercase, and consequently, `bind(...)` is no longer case-sensitive.
+
+However, the resulting `Configuration` object attribute names also become normalized to upper case which may not be desired by some developers.
+
+Probably most devs and devops working in enterprise environments will want to adopt `normalize=True` as a matter of practice. This will allow devops to conform around the use of upper-case key names in configuration systems, and allow devs to use whatever casing rules make the most sense for their projects (since `bind()` will still work as expected.) This does assume developers are creating concerete configuration types (you ARE doing that, correct?)
+
+I would have preferred to make `normalize=True` by default, but, I suspect someone out there will want to use `Configuration` instances directly rather than create bind targets and this would have resulted in attribute names that were upper case. To illustrate, from one of the early examples in this doc would instead look like this:
+
+```python
+value = configuration.CONNECTIONSTRINGS.SAMPLEDB # <-- this
+value = configuration.get('ConnectionStrings:SampleDb')
+value = configuration.get('ConnectionStrings__SampleDb')
+```
+
+In the future I may further abstract this detail away so we get the best of both worlds, but for now there is the parameter to let you control the behavior.
+
+## Conclusion
+
+If you made it this far, this library is probably what you were looking for. I'm certain there are other libraries which accomplish much of what I am attempting to accomplish here, but I wanted something i can directly support over the coming years. That, and the nearest equivalent to what I wanted fell out of active development nearly a decade ago and I just didn't feel comfortable adopting it for new work.
+

appsettings2-0.0.1/README.md

@@ -0,0 +1,216 @@
+# `appsettings2`
+
+A python library that unifies configuration sources into a Configuration object that can be bound to complex types, or accessed directly for configuration data.
+
+## Why?
+
+Because I write a lot of containerized applications where I typically supply configuration settings using a combination of Configuration Files and Environment Variables.
+
+When I debug those applications I often need to override Confguration using Command-Line Arguments, Configuration Files, Environment Variables, or a combination thereof.
+
+## Usage
+
+Construct a `ConfigurationBuilder` instance, add one or more `ConfigurationProvider` instances to it, and then use it to build a `Configuration` object containing your unified configuration data.
+
+```python
+from appsettings2 import *
+from appsettings2.providers import *
+
+def get_configuration() -> Configuration:
+    return ConfigurationBuilder()\
+        .addProvider(JsonConfigurationProvider(f'appsettings.json'))\
+        .addProvider(JsonConfigurationProvider(f'appsettings.Development.json', required=False))\
+        .addProvider(EnvironmentConfigurationProvider())\
+        .build()
+```
+
+In the above example two JSON Configuration Providers are added to the builder. The first will fail if "appsettings.json" is not found, the second will succeed whether or not the "appsettings.Development.json" exists (because `required=False`). This allows for an optional development configuration to exist on development workstations without requiring a code change.
+
+A third Configuration Provider is also added, an `EnvironmentConfigurationProvider`, which allows configuration to be loaded from Environment Variables.
+
+The order of providers determines precedence of configuration data. Providers added last will take precedence over providers added first. Values which are not provided by later registrations will not override values provided by earlier registrations.
+
+Given the example above, this means that configuration data provided via Environment Variables will override configuration data provided via JSON files.
+
+## Accssing Configuration Data
+
+There are two methods of directly accessing Configuration data directly. The first is by using first-class attributes in python, and the second is by using a `get(...)` method. 
+
+Consider the following code which demonstrates both methods, where all three of these statements are equivalent:
+
+```python
+value = configuration.ConnectionStrings.SampleDb
+value = configuration.get('ConnectionStrings:SampleDb')
+value = configuration.get('ConnectionStrings__SampleDb')
+```
+
+When accessing hierarchical data you can use a double-underscore delimiter or a colon delimiter, they are equivalent. Devs and Ops from different walks will likely prefer one form over the other, so both are supported.
+
+## Binding to Configuration Data
+
+It's also possible to bind configuration data to complex types. While some of the implementation is currently naive, it should work well for the vast majority of use-cases. If you find your particular edge case does not work well please reach out to me and I will work with you to implement a sensible solution.  Consider the following Python code:
+
+```python
+json = """{
+  "ConnectionStrings": {
+    "SampleDb": "my_cxn_string"
+  },
+  "EnableSwagger": true,
+  "MaxBatchSize": 100
+}"""
+
+class ConnStrs:
+    """An ugly class name to demonstrate the class name does not matter."""
+    SampleDb:str = None
+
+class AppSettings:
+    ConnectionStrings:ConnStrs = None
+    EnableSwagger:bool = None
+    MaxBatchSize:int = None
+
+configuration = ConfigurationBuilder()\
+    .addProvider(JsonConfigurationProvider(json=json))
+    .build()
+
+settings = AppSettings()
+configuration.bind(settings)
+```
+
+The resulting `settings` object will contain all of the configuration data properly typed according to type hints.
+
+It is also possible to bind to a subset of a configuration, building upon the above, consider the following:
+
+```python
+connectionStrings = configuration.bind(ConnectionStrings(), 'ConnectionStrings')
+```
+
+### Projecting Configuration Data as a Dictionary
+
+Laslty, as a convenience item you can materialize a `Configuration` instance as a Dictionary. This is primarily included as a debugging aid, but, if you have some chunk of code that can consume a dictionary but can't consume a Python object (it happens) then you can get at a dictionary as follows:
+
+```python
+config:Configuration = builder.build()
+my_dict = config.toDictionary()
+print(my_dict)
+```
+
+## Providers
+
+### Command-Line
+
+The `CommandLineConfigurationProvider` allows configuration data to be provided via command-line interface. This provider will process variables in the following forms as key-value pairs:
+
+```
+--ConnectionStrings__SampleDb 'my_connection_string'
+```
+
+```
+'ConnectionStrings__SampleDb=my_connection_string'
+```
+
+```
+--ConnectionStrings__SampleDb=my_connection_string
+```
+
+All three of these forms result in a configuration object with the following state (represented as JSON):
+
+```json
+{
+    "ConnectionStrings" : {
+        "SampleDb": "my_connection_string"
+    }
+}
+```
+
+Take note that the leading dashes are stripped.
+
+This double-underscore convention is a convention borrowed from other platforms/frameworks.
+
+It's also possible to use a colon in lieu of a double_underscore, but this may have unintended side-effects depending on the shell or platform being used:
+
+```
+'ConnectionStrings:SampleDb=my_connection_string'
+```
+
+This provider was implemented in a way that it does not interfere with libraries such as `argparse`, and should work as expected with a well-formed command-line interface. 
+
+### Environment Variables
+
+The `EnvironmentConfigurationProvider` consumes environment variables as key-value pairs. For example, consider these `bash` exports:
+
+```bash
+export ConnectionStrings__SampleDb=my_cxn_string
+export ConnectionStrings__AnotherDb=another_cxn_string
+```
+
+The above will resule in a Configuration object with the following state (represented as JSON):
+
+```json
+{
+    "ConnectionStrings": {
+        "SampleDb": "my_cxn_string",
+        "AnotherDb": "another_cxn_string"
+    }
+}
+```
+
+### JSON
+
+The `JsonConfigurationProvider` class allows you to load configuration data from a JSON file, JSON string, or JSON stream. Consider the following JSON:
+
+```json
+{
+    "Logging": {
+        "Default": "Debug"
+    },
+    "ConnectionStrings": {
+        "SampleDb": "my_cxn_string"
+    },
+}
+```
+
+When loaded using `JsonConfigurationProvider` the resulting `Configuration` object will have attribute names and a structure which matches the JSON, consider the following Python code (where "example.json" contains the above JSON):
+
+```python
+from appsettings2 import *
+from appsettings2.providers import *
+
+config = ConfigurationBuilder(normalize=True)\
+    .addProvider(JsonConfigurationProvider('example.json'))\
+    .build()
+
+print(config.ConnectionStrings.SampleDb)
+```
+Outputs: `my_cxn_string` (as expected.)
+
+### TOML
+
+The `TomlConfigurationProvider` should be functionally identical to the JSON provider, with the obvious difference that it loads Configuration data from a toml file.
+
+### YAML
+
+The `YamlConfigurationProvider` should be functionally identical to the JSON and TOML providers, with the obvious difference that it loads Configuration data from a yaml file.
+
+## A note on `normalize` parameters..
+
+`ConfigurationBuilder` accepts a parameter `normalize:bool` which defaults to `False` causing `bind()` to behave in a case-sensitive fashion.
+
+When set to `True` it causes the internal implementation of `Configuration` to normalize all configuration keys to uppercase, and consequently, `bind(...)` is no longer case-sensitive.
+
+However, the resulting `Configuration` object attribute names also become normalized to upper case which may not be desired by some developers.
+
+Probably most devs and devops working in enterprise environments will want to adopt `normalize=True` as a matter of practice. This will allow devops to conform around the use of upper-case key names in configuration systems, and allow devs to use whatever casing rules make the most sense for their projects (since `bind()` will still work as expected.) This does assume developers are creating concerete configuration types (you ARE doing that, correct?)
+
+I would have preferred to make `normalize=True` by default, but, I suspect someone out there will want to use `Configuration` instances directly rather than create bind targets and this would have resulted in attribute names that were upper case. To illustrate, from one of the early examples in this doc would instead look like this:
+
+```python
+value = configuration.CONNECTIONSTRINGS.SAMPLEDB # <-- this
+value = configuration.get('ConnectionStrings:SampleDb')
+value = configuration.get('ConnectionStrings__SampleDb')
+```
+
+In the future I may further abstract this detail away so we get the best of both worlds, but for now there is the parameter to let you control the behavior.
+
+## Conclusion
+
+If you made it this far, this library is probably what you were looking for. I'm certain there are other libraries which accomplish much of what I am attempting to accomplish here, but I wanted something i can directly support over the coming years. That, and the nearest equivalent to what I wanted fell out of active development nearly a decade ago and I just didn't feel comfortable adopting it for new work.

appsettings2-0.0.1/pyproject.toml

@@ -0,0 +1,26 @@
+[tool.poetry]
+name = "appsettings2"
+version = "0.0.1"
+description = "A python library that unifies configuration sources into a Configuration object that can be bound to complex types, or accessed directly for configuration data."
+authors = ["Shaun Wilson <mrshaunwilson@msn.com>"]
+license = "MIT"
+readme = "README.md"
+exclude = [
+    "tests"
+]
+packages = [
+    { include = "**/*.py", from = "src", to = "appsettings2", format = ["sdist", "wheel"] }
+]
+
+[tool.poetry.urls]
+documentation = "https://github.com/wilson0x4d/appsettings2/README.md"
+homepage = "https://github.com/wilson0x4d/appsettings2"
+repository = "https://github.com/wilson0x4d/appsettings2.git"
+
+[tool.poetry.dependencies]
+python = "^3.11"
+pyyaml = "^6.0.2"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

appsettings2-0.0.1/src/Configuration.py

@@ -0,0 +1,113 @@
+# SPDX-FileCopyrightText: © 2024 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from . import ConfigurationException
+import json
+import types
+from typing import Any, TypeAlias, get_type_hints
+
+any:TypeAlias = Any
+
+class Configuration:
+    """A configuration class which creates a layer of indirection between configuration providers and configuration consumers."""
+
+    __normalize:bool
+
+    def __init__(self, *, normalize:bool = False):
+        """By default keys are ingest as-is, pass `True` for `normalize` to normalize kets to lower case."""
+        self.__normalize = normalize
+
+    def __str__(self) -> str:
+        d:dict = self.toDictionary()
+        return json.dumps(d)
+    
+    def __recursiveBind(self, target:object, source:'Configuration') -> any:
+        targetTypeHints = get_type_hints(target)
+        for aname in dir(target):
+            if aname.startswith('_'):
+                continue
+            lval = getattr(target, aname)
+            if isinstance(lval, types.FunctionType) or isinstance(lval, types.MethodType):
+                continue
+            ahint = targetTypeHints.get(aname)
+            ahintstr = str(ahint)
+            rval = source.get(aname)
+            if isinstance(rval, Configuration):
+                if ahint is dict or ahintstr.startswith('dict['):
+                    lval = rval.toDictionary()
+                    setattr(target, aname, lval)
+                elif ahint is list or ahintstr.startswith('list['):
+                    # naive behavior
+                    setattr(target, aname, rval)
+                else:
+                    if lval == None:
+                        lval = ahint()
+                        setattr(target, aname, lval)
+                    self.__recursiveBind(lval, rval)
+            elif rval != None:
+                if ahint is float:
+                    v = float(rval)
+                    setattr(target, aname, v)
+                elif ahint is int:
+                    v = int(rval)
+                    setattr(target, aname, v)
+                elif ahint is str:
+                    v = str(rval)
+                    setattr(target, aname, v)
+                else:
+                    # naive behavior
+                    setattr(target, aname, rval)
+            else:
+                setattr(target, aname, None)
+        return target
+
+    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."""
+        if not target:
+            raise ConfigurationException('Missing required argument: target')
+        if key == None:
+            return self.__recursiveBind(target, self)
+        else:
+            return self.__recursiveBind(target, self.get(key))
+
+    def get(self, key:str, default:any = None) -> any:
+        """Gets the configuration element associated with the specified key."""
+        if self.__normalize:
+            key = key.lower()
+        parts = key.replace('__', '.').replace(':', '.').split('.')
+        o = self
+        for part in parts:
+            if not hasattr(o, part):
+                return default
+            o = getattr(o, part)
+        return o
+
+    def set(self, key:str, value:any) -> None:
+        """Sets the configuration element for the specified key."""
+        if self.__normalize:
+            key = key.lower()
+        parts = key.replace('__', '.').replace(':', '.').split('.')
+        o = self
+        for i in range(len(parts) - 1):
+            if not hasattr(o, parts[i]):
+                setattr(o, parts[i], Configuration(normalize=self.__normalize))
+            o = getattr(o, parts[i])
+        if hasattr(o, parts[-1]):
+            delattr(o, parts[-1])
+        setattr(o, parts[-1], value)
+
+    def toDictionary(self) -> dict:
+        """Projects a dictionary from the configuration object."""
+        result = {}
+        for aname in dir(self):
+            if aname.startswith('_'):
+                continue
+            aval = getattr(self, aname)
+            if isinstance(aval, types.FunctionType) or isinstance(aval, types.MethodType):
+                continue
+            if isinstance(aval, Configuration):
+                aval = aval.toDictionary()
+            result[aname] = aval
+        return result

appsettings2-0.0.1/src/ConfigurationBuilder.py

@@ -0,0 +1,32 @@
+# SPDX-FileCopyrightText: © 2024 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from . import Configuration, ConfigurationException
+from .providers import ConfigurationProvider
+import typing
+
+any: typing.TypeAlias = typing.Any
+
+class ConfigurationBuilder:
+    """A class which builds a Configuration object from one ore more ConfigurationProvider instances."""
+
+    __normalize:bool
+    __providers:list[ConfigurationProvider]
+
+    def __init__(self, *, normalize:bool = False):
+        self.__normalize = normalize
+        self.__providers = []
+
+    def addProvider(self, provider:ConfigurationProvider) -> 'ConfigurationBuilder':
+        """Adds the specified provider to this builder instance."""
+        if not provider:
+            raise ConfigurationException('Missing required argument: provider')
+        self.__providers.append(provider)
+        return self
+
+    def build(self) -> Configuration:
+        """Builds a Configuration object from all providers which have been added to this builder."""
+        configuration = Configuration(normalize=self.__normalize)
+        for provider in self.__providers:
+            provider.populateConfiguration(configuration)
+        return configuration

appsettings2-0.0.1/src/ConfigurationException.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: © 2024 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+class ConfigurationException(Exception):
+    """An exception raised by `appsettings2` library."""
+    def __init__(self, reason:str):
+        super().__init__(reason)

appsettings2-0.0.1/src/__init__.py

@@ -0,0 +1,9 @@
+# SPDX-FileCopyrightText: © 2024 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from .providers import *
+from .Configuration import Configuration
+from .ConfigurationBuilder import ConfigurationBuilder
+from .ConfigurationException import ConfigurationException
+
+__version__ = '0.0.1'

appsettings2-0.0.1/src/providers/CommandLineConfigurationProvider.py

@@ -0,0 +1,39 @@
+# SPDX-FileCopyrightText: © 2024 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from . import ConfigurationProvider
+from .. import Configuration
+import sys
+
+class CommandLineConfigurationProvider(ConfigurationProvider):
+    """Processes the command-line and provides args as Configuration data."""
+
+    __argv:list[str]
+
+    def __init__(self, argv:list[str] = None):
+        self.__argv = argv if argv != None else sys.argv
+
+    def populateConfiguration(self, configuration:Configuration):
+        if self.__argv == None:
+            return
+        pending_key = None
+        for arg in self.__argv:
+            safe_arg = arg.lstrip('-')
+            eqidx = safe_arg.find('=')
+            if pending_key:
+                if (not arg.startswith('-')) and (eqidx < 1):
+                    k = pending_key
+                    v = arg.lstrip('=')
+                    configuration.set(k, v)
+                    continue
+                else:
+                    configuration.set(pending_key, True)
+                    pending_key = None
+            if eqidx > 0:
+                k = safe_arg[0:eqidx]
+                v = safe_arg[eqidx+1:len(safe_arg)]
+                configuration.set(k, v)
+            elif arg.startswith('--'):
+                pending_key = safe_arg
+        if pending_key != None:
+            configuration.set(pending_key, True)

appsettings2-0.0.1/src/providers/ConfigurationProvider.py

@@ -0,0 +1,12 @@
+# SPDX-FileCopyrightText: © 2024 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from .. import Configuration
+from abc import ABC as abstract, abstractmethod
+
+class ConfigurationProvider(abstract):
+
+    @abstractmethod
+    def populateConfiguration(self, configuration:Configuration) -> None:
+        """The ConfigurationProvider will populate the provided Configuration instance."""
+        pass

appsettings2-0.0.1/src/providers/EnvironmentConfigurationProvider.py

@@ -0,0 +1,13 @@
+# SPDX-FileCopyrightText: © 2024 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from . import ConfigurationProvider
+from .. import Configuration
+import os
+
+class EnvironmentConfigurationProvider(ConfigurationProvider):
+    """Processes environment variables and provides them as Configuration data."""
+
+    def populateConfiguration(self, configuration:Configuration):
+        for k in os.environ:
+            configuration.set(k, os.environ[k])

appsettings2-0.0.1/src/providers/JsonConfigurationProvider.py

@@ -0,0 +1,47 @@
+# SPDX-FileCopyrightText: © 2024 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from . import ConfigurationProvider
+from .. import Configuration, ConfigurationException
+import json as _json
+import os
+from typing import Any, TypeAlias
+
+FileDescriptor: TypeAlias = int
+any: TypeAlias = Any
+
+class JsonConfigurationProvider(ConfigurationProvider):
+    """Processes a json string, json file, or json stream and provides the content as Configuration data."""
+
+    __obj:dict
+
+    def __init__(self, filepath:str = None, *, json:str = None, fd:FileDescriptor = None, required:bool = True):
+        if filepath:
+            if os.path.isfile(filepath):
+                with open(filepath, 'rt') as file:
+                    json = file.read()
+            elif required:
+                raise ConfigurationException(f'Missing required file: {filepath}')
+        elif fd:
+            with open(fd, 'rt') as file:
+                json = file.read()
+        if json:
+            self.__obj = _json.loads(json)
+        else:
+            self.__obj = None
+
+    def __populateRecursive(self, configuration:Configuration, prefix:str, o:dict):
+        for kvp in o.items():
+            if isinstance(kvp[1], dict):
+                self.__populateRecursive(configuration, f'{prefix}__{kvp[0]}', kvp[1])
+            else:
+                configuration.set(f'{prefix}__{kvp[0]}', kvp[1])
+
+    def populateConfiguration(self, configuration:Configuration):
+        if self.__obj == None:
+            return
+        for kvp in self.__obj.items():
+            if isinstance(kvp[1], dict):
+                self.__populateRecursive(configuration, kvp[0], kvp[1])
+            else:
+                configuration.set(f'{kvp[0]}', kvp[1])

appsettings2-0.0.1/src/providers/TomlConfigurationProvider.py

@@ -0,0 +1,47 @@
+# SPDX-FileCopyrightText: © 2024 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from . import ConfigurationProvider
+from .. import Configuration, ConfigurationException
+import os
+import tomllib as _toml
+from typing import Any, TypeAlias
+
+FileDescriptor: TypeAlias = int
+any: TypeAlias = Any
+
+class TomlConfigurationProvider(ConfigurationProvider):
+    """Processes a toml string, toml file, or toml stream and provides the content as Configuration data."""
+
+    __obj:dict
+
+    def __init__(self, filepath:str = None, *, toml:str = None, fd:FileDescriptor = None, required:bool = True):
+        if filepath:
+            if os.path.isfile(filepath):
+                with open(filepath, 'rt') as file:
+                    toml = file.read()
+            elif required:
+                raise ConfigurationException(f'Missing required file: {filepath}')
+        elif fd:
+            with open(fd, 'rt') as file:
+                toml = file.read()
+        if toml:
+            self.__obj = _toml.loads(toml)
+        else:
+            self.__obj = None
+
+    def __populateRecursive(self, configuration:Configuration, prefix:str, o:dict):
+        for kvp in o.items():
+            if isinstance(kvp[1], dict):
+                self.__populateRecursive(configuration, f'{prefix}__{kvp[0]}', kvp[1])
+            else:
+                configuration.set(f'{prefix}__{kvp[0]}', kvp[1])
+
+    def populateConfiguration(self, configuration:Configuration):
+        if self.__obj == None:
+            return
+        for kvp in self.__obj.items():
+            if isinstance(kvp[1], dict):
+                self.__populateRecursive(configuration, kvp[0], kvp[1])
+            else:
+                configuration.set(f'{kvp[0]}', kvp[1])

appsettings2-0.0.1/src/providers/YamlConfigurationProvider.py

@@ -0,0 +1,50 @@
+# SPDX-FileCopyrightText: © 2024 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from . import ConfigurationProvider
+from .. import Configuration, ConfigurationException
+from io import StringIO
+import os
+from typing import Any, TypeAlias
+import yaml as _yaml
+
+FileDescriptor: TypeAlias = int
+any: TypeAlias = Any
+
+class YamlConfigurationProvider(ConfigurationProvider):
+    """Processes a yaml string, yaml file, or yaml stream and provides the content as Configuration data."""
+
+    __obj:dict
+
+    def __init__(self, filepath:str = None, *, yaml:str = None, fd:FileDescriptor = None, required:bool = True):
+        if filepath:
+            if os.path.isfile(filepath):
+                with open(filepath, 'rt') as file:
+                    self.__obj = _yaml.safe_load(file)
+            elif required:
+                raise ConfigurationException(f'Missing required file: {filepath}')
+        elif fd:
+            with open(fd, 'rt') as file:
+                self.__obj = _yaml.safe_load(file)
+        elif yaml:
+            stream = StringIO(yaml)
+            self.__obj = _yaml.safe_load(stream)
+            stream.close()
+        else:
+            self.__obj = None
+
+    def __populateRecursive(self, configuration:Configuration, prefix:str, o:dict):
+        for kvp in o.items():
+            if isinstance(kvp[1], dict):
+                self.__populateRecursive(configuration, f'{prefix}__{kvp[0]}', kvp[1])
+            else:
+                configuration.set(f'{prefix}__{kvp[0]}', kvp[1])
+
+    def populateConfiguration(self, configuration:Configuration):
+        if self.__obj == None:
+            return
+        for kvp in self.__obj.items():
+            if isinstance(kvp[1], dict):
+                self.__populateRecursive(configuration, kvp[0], kvp[1])
+            else:
+                configuration.set(f'{kvp[0]}', kvp[1])

appsettings2-0.0.1/src/providers/__init__.py

@@ -0,0 +1,9 @@
+# SPDX-FileCopyrightText: © 2024 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from .ConfigurationProvider import ConfigurationProvider
+from .CommandLineConfigurationProvider import CommandLineConfigurationProvider
+from .EnvironmentConfigurationProvider import EnvironmentConfigurationProvider
+from .JsonConfigurationProvider import JsonConfigurationProvider
+from .TomlConfigurationProvider import TomlConfigurationProvider
+from .YamlConfigurationProvider import YamlConfigurationProvider