appsettings2 0.1.4__tar.gz → 0.3.0__tar.gz

{appsettings2-0.1.4 → appsettings2-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: appsettings2
-Version: 0.1.4
+Version: 0.3.0
 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
@@ -199,7 +199,7 @@ When loaded using `JsonConfigurationProvider` the resulting `Configuration` obje
 from appsettings2 import *
 from appsettings2.providers import *
 
-config = ConfigurationBuilder(normalize=True)\
+config = ConfigurationBuilder()\
     .addProvider(JsonConfigurationProvider('example.json'))\
     .build()
 
@@ -215,25 +215,88 @@ The `TomlConfigurationProvider` should be functionally identical to the JSON pro
 
 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..
+## Special Attribute Name Handling
 
-`ConfigurationBuilder` accepts a parameter `normalize:bool` which defaults to `False` causing `bind()` to behave in a case-sensitive fashion.
+### Upper-Case Attribute Names
 
-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.
+`ConfigurationBuilder` accepts a parameter `normalize:bool` which defaults to `False` causing `Configuration` attributes to preserve the casing of keys from the input configuration.
 
-However, the resulting `Configuration` object attribute names also become normalized to upper case which may not be desired by some developers.
+If you pass `normalize=True`, all `Configuration` instances created by that builder will normalize `Configuration` attributes to upper-case.
 
-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?)
+In both cases the `Configuration` object allows access to data in a case-insensitive fashion. Normalization _ONLY_ affects the resulting object attributes.
 
-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, one of the early examples in this doc would instead look like this:
+To illustrate, consider the following snippet:
 
 ```python
-value = configuration.CONNECTIONSTRINGS.SAMPLEDB # <-- this
-value = configuration.get('ConnectionStrings:SampleDb')
-value = configuration.get('ConnectionStrings__SampleDb')
+configuration = Configuration(normalize=True)
+configuration.set('ConnectionStrings__SampleDb', 'blah')
+# normalized attributes looks like this:
+value = configuration.CONNECTIONSTRINGS.SAMPLEDB
+# but you can still access the data case-insensitive:
+value = configuration.get('connectionstrings__SAMPLEDB')
+value = configuration['cOnNeCtioNsTriNGs']['sampledb']
+# however, by default (where normalize=False):
+configuration = Configuration()
+configuration.set('ConnectionStrings__SampleDb', 'blah')
+# attributes look like this:
+value = configuration.ConnectionStrings.SampleDb
+# and as before, you have case-insensitive access:
+value = configuration.get('connectionstrings__SAMPLEDB')
+value = configuration['cOnNeCtioNsTriNGs']['sampledb']
+```
+
+Normalization has no effect on `bind(...)`, which operates in a case-insensitive fashion internally.
+
+### Lexer-friendly Attribute Names
+
+`ConfigurationBuilder` accepts a parameter `scrubkeys:bool` which defaults to `False` causing `Configuration` attributes to preserve the keys from the input configuration even if they would be inaccessible from Python code.
+
+If you pass `scrubkeys=True`, all `Configuration` instances created by that builder will generate lexically accessible `Configuration` attributes.
+
+This is not enabled by default because it introduces an edge case where configuration keys may collide, albeit very unlikely, this is explained below.
+
+Some configuration sources might produce attribute names which are not accessible from Python code. Consider the following JSON snippet:
+
+```json
+{
+  "query-tab" : {
+    "fragment#left": {
+        "input": true
+    }
+  }
+}
+```
+
+This configuration will load, and you can still access the data using keyed methods such as `get(...)` and `set(...)`, but the resulting `Configuration` object will have attributes that cannot be accessed from Python code:
+
+```python
+if True == configuration.query-tab.fragment#left.input:
+    pass
+```
+
+To accomodate configurations such as these and make them accessible via `Configuration` attributes you may pass `scrubkeys=True`. This will cause any lexically invalid characters to be transformed into an underscore `_` character.
+
+Although attribute names are transformed, keys are not. Therefore, given the above JSON snippet the following are equivalent:
+
+```python
+# access via object attributes
+configuration.query_tab.fragement_left.input
+# access using indexers
+configuration['query-tab']['fragment#left']
+# access using other 'key' methods
+configuration.get('query-tab').has_key('fragment#left')
+```
+
+Lastly, this _does_ make it possible for configuration values to collide, for example, these two keys will collide:
+
+```json
+{
+  "key#1": true,
+  "key-1": false
+}
 ```
 
-In the future I may 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.
+Attempting to access these values will result in a value of `False` being returned, and setting the value of one key will affect the value of the other, this is because internally there will be only one storage slot/attribute that is shared between them. Although an unlikely scenario, it is for this reason the feature is opt-in only.
 
 ## Conclusion
 

{appsettings2-0.1.4 → appsettings2-0.3.0}/README.md

@@ -178,7 +178,7 @@ When loaded using `JsonConfigurationProvider` the resulting `Configuration` obje
 from appsettings2 import *
 from appsettings2.providers import *
 
-config = ConfigurationBuilder(normalize=True)\
+config = ConfigurationBuilder()\
     .addProvider(JsonConfigurationProvider('example.json'))\
     .build()
 
@@ -194,25 +194,88 @@ The `TomlConfigurationProvider` should be functionally identical to the JSON pro
 
 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..
+## Special Attribute Name Handling
 
-`ConfigurationBuilder` accepts a parameter `normalize:bool` which defaults to `False` causing `bind()` to behave in a case-sensitive fashion.
+### Upper-Case Attribute Names
 
-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.
+`ConfigurationBuilder` accepts a parameter `normalize:bool` which defaults to `False` causing `Configuration` attributes to preserve the casing of keys from the input configuration.
 
-However, the resulting `Configuration` object attribute names also become normalized to upper case which may not be desired by some developers.
+If you pass `normalize=True`, all `Configuration` instances created by that builder will normalize `Configuration` attributes to upper-case.
 
-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?)
+In both cases the `Configuration` object allows access to data in a case-insensitive fashion. Normalization _ONLY_ affects the resulting object attributes.
 
-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, one of the early examples in this doc would instead look like this:
+To illustrate, consider the following snippet:
 
 ```python
-value = configuration.CONNECTIONSTRINGS.SAMPLEDB # <-- this
-value = configuration.get('ConnectionStrings:SampleDb')
-value = configuration.get('ConnectionStrings__SampleDb')
+configuration = Configuration(normalize=True)
+configuration.set('ConnectionStrings__SampleDb', 'blah')
+# normalized attributes looks like this:
+value = configuration.CONNECTIONSTRINGS.SAMPLEDB
+# but you can still access the data case-insensitive:
+value = configuration.get('connectionstrings__SAMPLEDB')
+value = configuration['cOnNeCtioNsTriNGs']['sampledb']
+# however, by default (where normalize=False):
+configuration = Configuration()
+configuration.set('ConnectionStrings__SampleDb', 'blah')
+# attributes look like this:
+value = configuration.ConnectionStrings.SampleDb
+# and as before, you have case-insensitive access:
+value = configuration.get('connectionstrings__SAMPLEDB')
+value = configuration['cOnNeCtioNsTriNGs']['sampledb']
+```
+
+Normalization has no effect on `bind(...)`, which operates in a case-insensitive fashion internally.
+
+### Lexer-friendly Attribute Names
+
+`ConfigurationBuilder` accepts a parameter `scrubkeys:bool` which defaults to `False` causing `Configuration` attributes to preserve the keys from the input configuration even if they would be inaccessible from Python code.
+
+If you pass `scrubkeys=True`, all `Configuration` instances created by that builder will generate lexically accessible `Configuration` attributes.
+
+This is not enabled by default because it introduces an edge case where configuration keys may collide, albeit very unlikely, this is explained below.
+
+Some configuration sources might produce attribute names which are not accessible from Python code. Consider the following JSON snippet:
+
+```json
+{
+  "query-tab" : {
+    "fragment#left": {
+        "input": true
+    }
+  }
+}
+```
+
+This configuration will load, and you can still access the data using keyed methods such as `get(...)` and `set(...)`, but the resulting `Configuration` object will have attributes that cannot be accessed from Python code:
+
+```python
+if True == configuration.query-tab.fragment#left.input:
+    pass
+```
+
+To accomodate configurations such as these and make them accessible via `Configuration` attributes you may pass `scrubkeys=True`. This will cause any lexically invalid characters to be transformed into an underscore `_` character.
+
+Although attribute names are transformed, keys are not. Therefore, given the above JSON snippet the following are equivalent:
+
+```python
+# access via object attributes
+configuration.query_tab.fragement_left.input
+# access using indexers
+configuration['query-tab']['fragment#left']
+# access using other 'key' methods
+configuration.get('query-tab').has_key('fragment#left')
+```
+
+Lastly, this _does_ make it possible for configuration values to collide, for example, these two keys will collide:
+
+```json
+{
+  "key#1": true,
+  "key-1": false
+}
 ```
 
-In the future I may 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.
+Attempting to access these values will result in a value of `False` being returned, and setting the value of one key will affect the value of the other, this is because internally there will be only one storage slot/attribute that is shared between them. Although an unlikely scenario, it is for this reason the feature is opt-in only.
 
 ## Conclusion
 

{appsettings2-0.1.4 → appsettings2-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "appsettings2"
-version = "0.1.4"
+version = "0.3.0"
 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"

{appsettings2-0.1.4 → appsettings2-0.3.0}/src/Configuration.py

@@ -3,44 +3,52 @@
 
 from . import ConfigurationException
 import json
+import re
 import types
 from typing import Any, TypeAlias, get_type_hints
+import unicodedata
 
 any:TypeAlias = Any
 
 class Configuration:
     """A configuration class which creates a layer of indirection between configuration providers and configuration consumers."""
 
+    __key_scrub_re:re.Pattern
+    __keys:dict[str, str]
     __normalize:bool
-    __len:int = 0
 
-    def __init__(self, *, normalize:bool = False):
+    def __init__(self, *, normalize:bool = False, scrubkeys:bool = False):
         """By default keys are ingest as-is, pass `True` for `normalize` to normalize kets to lower case."""
+        self.__keys = {}
         self.__normalize = normalize
+        self.__key_scrub_re = None if not scrubkeys else re.compile(r'[^A-Za-z0-9_]', re.IGNORECASE | re.UNICODE)
 
-    def __str__(self) -> str:
-        d:dict = self.toDictionary()
-        return json.dumps(d)
+    def __delitem__(self, key:str) -> None:
+        key = key.upper()
+        k = self.__keys.get(key)
+        if k != None:
+            delattr(self, k)
+            self.__keys.pop(key)
 
     def __getitem__(self, key:str) -> any:
-        if not hasattr(self, key):
-            raise KeyError()
-        else:
-            return self.get(key)
+        parts = key.replace('__', '.').replace(':', '.').split('.')
+        o = self
+        for part in parts:
+            if o == self:
+                k = self.__keys.get(part.upper())
+                if k == None:
+                    raise KeyError()
+                else:
+                    o = getattr(o, self.__scrub_key(k))
+            else:
+                o = o[part]
+        return o
 
     def __iter__(self):
-        return iter(self.keys())
+        return iter(self.__keys.values())
 
     def __len__(self) -> int:
-        return self.__len
-
-    def __setitem__(self, key:str, value:any) -> None:
-        self.set(key, value)
-
-    def __delitem__(self, key:str) -> None:
-        if hasattr(self, key):
-            delattr(self, key)
-            self.__len -= 1
+        return len(self.__keys)
 
     def __recursiveBind(self, target:object, source:'Configuration') -> any:
         targetTypeHints = get_type_hints(target)
@@ -58,8 +66,7 @@ class Configuration:
                     lval = rval.toDictionary()
                     setattr(target, aname, lval)
                 elif ahint is list or ahintstr.startswith('list['):
-                    # naive behavior
-                    setattr(target, aname, rval)
+                    raise ConfigurationException(f'lval ({ahint!r}) is incompatible with rval (Configuration)')
                 else:
                     if lval == None:
                         lval = ahint()
@@ -82,6 +89,31 @@ class Configuration:
                 setattr(target, aname, None)
         return target
 
+    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 None == self.__key_scrub_re else \
+            self.__key_scrub_re.sub(
+                self.__scrub_uc,
+                unicodedata.normalize(
+                    'NFKC',
+                    key))
+
+    def __scrub_uc(self, m:re.Match) -> str:
+        match unicodedata.category(m[0]):
+            case 'Lu' | 'Ll' | 'Lt' | 'Lm' | 'Lo' | 'Nl' | 'Mn' | 'Mc' | 'Nd' | 'Pc' :
+                return m[0]
+            case _:
+                return '_'
+
+    def __setitem__(self, key:str, value:any) -> None:
+        self.set(key, value)
+
+    def __str__(self) -> str:
+        return json.dumps(self.toDictionary())
+
     def bind(self, target:object, key:str|None = None) -> any:
         """Binds the configuration values into the target object.
         
@@ -94,46 +126,37 @@ class Configuration:
             return self.__recursiveBind(target, self.get(key))
 
     def clear(self) -> None:
-        for k in self.keys():
-            delattr(self, k)
-            self.__len -= 1
+        while len(self.__keys) > 0:
+            t = self.__keys.popitem()
+            delattr(self, t[1])
 
     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)
+            if o == self:
+                k = self.__keys.get(part.upper())
+                if k == None:
+                    return default
+                else:
+                    o = getattr(o, self.__scrub_key(k))
+            else:
+                o = o.get(part, default)
         return o
 
     def has_key(self, key:str) -> bool:
-        return hasattr(self, key)
+        return self.__keys.get(key.upper()) != None
 
     def items(self) -> list[tuple[str,any]]:
         it = []
-        for k in dir(self):
-            if k.startswith('_'):
-                continue
-            v = getattr(self, k)
-            if isinstance(v, types.FunctionType) or isinstance(v, types.MethodType):
-                continue
+        for k in self.keys():
+            v = self.get(k)
             it.append((k, v))
         return it
 
     def keys(self) -> list[str]:
-        keys = []
-        for k in dir(self):
-            if k.startswith('_'):
-                continue
-            v = getattr(self, k)
-            if isinstance(v, types.FunctionType) or isinstance(v, types.MethodType):
-                continue
-            keys.append(k)
-        return keys
+        return self.__keys.values()
 
     def pop(self, key:str) -> any:
         value = self[key]
@@ -143,46 +166,51 @@ class Configuration:
     def set(self, key:str, value:any) -> None:
         """Sets the configuration element for the specified key."""
         if self.__normalize:
-            key = key.lower()
+            key = key.upper()
         parts = key.replace('__', '.').replace(':', '.').split('.')
         o = self
         for i in range(len(parts) - 1):
-            if not hasattr(o, parts[i]):
-                c = Configuration(normalize=self.__normalize)
-                o.set(parts[i], c)
-                o = c
+            if o == self:
+                k = self.__keys.get(parts[i].upper())
+                if k == None:
+                    c = Configuration(normalize=self.__normalize, scrubkeys=(None != self.__key_scrub_re))
+                    setattr(o, self.__scrub_key(parts[i]), c)
+                    self.__keys[parts[i].upper()] = parts[i]
+                    o = c
+                else:
+                    o = getattr(self, self.__scrub_key(k))
             else:
-                o = getattr(o, parts[i])
+                if not o.has_key(parts[i]):
+                    c = Configuration(normalize=self.__normalize, scrubkeys=(None != self.__key_scrub_re))
+                    o.set(parts[i], c)
+                    o = c
+                else:
+                    o = o.get(parts[i])
+        key = parts[-1]
         if o == self:
-            if hasattr(o, parts[-1]):
-                delattr(o, parts[-1])
+            k = self.__keys.get(key.upper())
+            if k != None:
+                setattr(self, self.__scrub_key(k), value)
             else:
-                self.__len += 1
-            setattr(self, parts[-1], value)
+                self.__keys[key.upper()] = key
+                setattr(self, self.__scrub_key(key), value)
         else:
-            o.set(parts[-1], value)
+            o.set(key, 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
+        for k in self.__keys.values():
+            v = getattr(self, self.__scrub_key(k))
+            if isinstance(v, Configuration):
+                result[k] = v.toDictionary()
+            else:
+                result[k] = v
         return result
 
     def values(self) -> list[any]:
         values = []
-        for k in dir(self):
-            if k.startswith('_'):
-                continue
-            v = getattr(self, k)
-            if isinstance(v, types.FunctionType) or isinstance(v, types.MethodType):
-                continue
+        for k in self.__keys.values():
+            v = getattr(self, self.__scrub_key(k))
             values.append(v)
         return values

{appsettings2-0.1.4 → appsettings2-0.3.0}/src/ConfigurationBuilder.py

@@ -13,8 +13,9 @@ class ConfigurationBuilder:
     __normalize:bool
     __providers:list[ConfigurationProvider]
 
-    def __init__(self, *, normalize:bool = False):
+    def __init__(self, *, normalize:bool = False, scrubkeys:bool = False):
         self.__normalize = normalize
+        self.__scrubkeys = scrubkeys
         self.__providers = []
 
     def addProvider(self, provider:ConfigurationProvider) -> 'ConfigurationBuilder':
@@ -26,7 +27,7 @@ class ConfigurationBuilder:
 
     def build(self) -> Configuration:
         """Builds a Configuration object from all providers which have been added to this builder."""
-        configuration = Configuration(normalize=self.__normalize)
+        configuration = Configuration(normalize=self.__normalize, scrubkeys=self.__scrubkeys)
         for provider in self.__providers:
             provider.populateConfiguration(configuration)
         return configuration

{appsettings2-0.1.4 → appsettings2-0.3.0}/src/__init__.py

@@ -6,4 +6,4 @@ from .Configuration import Configuration
 from .ConfigurationBuilder import ConfigurationBuilder
 from .ConfigurationException import ConfigurationException
 
-__version__ = '0.1.4'
+__version__ = '0.3.0'