Add merge function and enable union operator between Configuration instances / applicable source types

CHANGES.md

@@ -4,6 +4,9 @@ Changes
 development (master)
 --------------------
 
+- Add `merge` function to combine multiple mappings into a single `Configuration`.
+- Enable the use of the binary or / union operator on `Configuration` instances, analogous to a builtin `dict` (e.g. `config = defaults | overrides`).
+
 0.15 (2023-06-26)
 -----------------
 

confidence/__init__.py

@@ -2,13 +2,13 @@
 
 from confidence.exceptions import ConfigurationError, ConfiguredReferenceError, MergeConflictError, NotConfiguredError
 from confidence.io import DEFAULT_LOAD_ORDER, dump, dumpf, dumps, load, load_name, loaders, loadf, loads, Locality
-from confidence.models import Configuration, Missing, NotConfigured, unwrap
+from confidence.models import Configuration, merge, Missing, NotConfigured, unwrap
 
 
 __all__ = (
     'ConfigurationError', 'ConfiguredReferenceError', 'MergeConflictError', 'NotConfiguredError',
     'DEFAULT_LOAD_ORDER', 'dump', 'dumpf', 'dumps', 'load', 'load_name', 'loaders', 'loadf', 'loads', 'Locality',
-    'Configuration', 'Missing', 'NotConfigured', 'unwrap',
+    'Configuration', 'merge', 'Missing', 'NotConfigured', 'unwrap',
 )
 
 

confidence/models.py

@@ -5,7 +5,7 @@
 import typing
 
 from confidence.exceptions import ConfiguredReferenceError, NotConfiguredError
-from confidence.utils import Conflict, merge, split_keys
+from confidence.utils import Conflict, merge_into, split_keys
 
 
 class Missing(Enum):
@@ -46,6 +46,29 @@ def unwrap(source: typing.Any) -> typing.Any:
     return source
 
 
+def merge(*sources: typing.Mapping[str, typing.Any], missing: typing.Any = None) -> 'Configuration':
+    """
+    Merges *sources* into a union, keeping right-side precedence.
+
+    :param sources: source mappings to base the union on, ordered from least to
+        most significance
+    :param missing: policy for the resulting `Configuration` (defaults to
+        `Missing.SILENT`)
+    :return: a `Configuration` instance that encompasses all of the keys and
+        values in *sources*
+    :raises ValueError: when the missing policies of *source* cannot be aligned
+    """
+    if missing is None:
+        # no explicit missing setting, collect settings from arguments, should be either nothing if sources are not
+        # Configuration instances, or a single overlapping value, refuse union otherwise
+        if len(missing := {source._missing for source in sources if isinstance(source, Configuration)}) > 1:
+            raise ValueError(f'no union for incompatible instances: {missing}')
+        # use the one remaining missing setting, or default to Missing.SILENT
+        missing = missing.pop() if missing else Missing.SILENT
+
+    return Configuration(*sources, missing=missing)
+
+
 class Configuration(Mapping):
     """
     A collection of configured values, retrievable as either `dict`-like items
@@ -80,7 +103,11 @@ def __init__(self,
             if source:
                 # merge values from source into self._source, overwriting any corresponding keys
                 # unwrap the source to make sure we're dealing with simple types
-                merge(self._source, split_keys(unwrap(source), colliding=_COLLIDING_KEYS), conflict=Conflict.OVERWRITE)
+                merge_into(
+                    self._source,
+                    split_keys(unwrap(source), colliding=_COLLIDING_KEYS),
+                    conflict=Conflict.OVERWRITE,
+                )
 
     def _wrap(self, value: typing.Mapping[str, typing.Any]) -> 'Configuration':
         # create an instance of our current type, copying 'configured' properties / policies
@@ -229,6 +256,9 @@ def __getitem__(self, item: str) -> typing.Any:
     def __iter__(self) -> typing.Iterator[str]:
         return iter(self._source)
 
+    def __or__(self, other: typing.Mapping[str, typing.Any]) -> 'Configuration':
+        return merge(self, other)
+
     def __dir__(self) -> typing.Iterable[str]:
         return sorted(set(chain(super().__dir__(), self.keys())))
 
@@ -263,6 +293,7 @@ def __setstate__(self, state: typing.Dict[str, typing.Any]) -> None:
     '__repr__': lambda self: '(not configured)',
     '__str__': lambda self: '(not configured)',
     '__doc__': 'Sentinel value to signal there is no value for a requested key.',
+    '__hash__': lambda self: hash((type(self), None)),
 })
 # overwrite the NotConfigured type as an instance of itself, serving as a sentinel value that some requested key was
 # not configured, while still acting like a Configuration object

confidence/utils.py

@@ -2,6 +2,7 @@
 from enum import IntEnum
 import logging
 import typing
+import warnings
 
 from confidence.exceptions import MergeConflictError
 
@@ -14,10 +15,10 @@ class Conflict(IntEnum):
     ERROR = 1
 
 
-def merge(left: typing.MutableMapping[str, typing.Any],
-          right: typing.Mapping[str, typing.Any],
-          path: typing.Optional[typing.List[str]] = None,
-          conflict: Conflict = Conflict.ERROR) -> typing.Mapping[str, typing.Any]:
+def merge_into(left: typing.MutableMapping[str, typing.Any],
+               right: typing.Mapping[str, typing.Any],
+               path: typing.Optional[typing.List[str]] = None,
+               conflict: Conflict = Conflict.ERROR) -> typing.Mapping[str, typing.Any]:
     """
     Merges values in place from *right* into *left*.
 
@@ -38,7 +39,7 @@ def merge(left: typing.MutableMapping[str, typing.Any],
         if key in left:
             if isinstance(left[key], Mapping) and isinstance(right[key], Mapping):
                 # recurse, merge left and right dict values, update path for current 'step'
-                merge(left[key], right[key], path + [key], conflict=conflict)
+                merge_into(left[key], right[key], path + [key], conflict=conflict)
             elif left[key] != right[key]:
                 if conflict is Conflict.ERROR:
                     # not both dicts we could merge, but also not the same, this doesn't work
@@ -95,6 +96,20 @@ def split_keys(mapping: typing.Mapping[str, typing.Any],
             LOG.warning('key "%s" collides with a named member, use the get() method to retrieve its value', key)
 
         # merge the result so far with the (possibly updated / fixed / split) current key and value
-        merge(result, {key: value})
+        merge_into(result, {key: value})
 
     return result
+
+
+# retained to compatibility only (warn about the rename, though)
+def merge(left: typing.MutableMapping[str, typing.Any],
+          right: typing.Mapping[str, typing.Any],
+          path: typing.Optional[typing.List[str]] = None,
+          conflict: Conflict = Conflict.ERROR) -> typing.Mapping[str, typing.Any]:
+    warnings.warn(
+        'confidence.utils.merge has been renamed to confidence.utils.merge_into '
+        'and will be removed in a future version',
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return merge_into(left, right, path, conflict)