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

CHANGES.md

@@ -4,6 +4,9 @@ Changes
 development (master)
 --------------------
 
+- Add `union` 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, Missing, NotConfigured, union, unwrap
 
 
 __all__ = (
     'ConfigurationError', 'ConfiguredReferenceError', 'MergeConflictError', 'NotConfiguredError',
     'DEFAULT_LOAD_ORDER', 'dump', 'dumpf', 'dumps', 'load', 'load_name', 'loaders', 'loadf', 'loads', 'Locality',
-    'Configuration', 'Missing', 'NotConfigured', 'unwrap',
+    'Configuration', 'Missing', 'NotConfigured', 'union', 'unwrap',
 )
 
 

confidence/models.py

@@ -46,6 +46,29 @@ def unwrap(source: typing.Any) -> typing.Any:
     return source
 
 
+def union(*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
@@ -229,6 +252,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 union(self, other)
+
     def __dir__(self) -> typing.Iterable[str]:
         return sorted(set(chain(super().__dir__(), self.keys())))
 
@@ -263,6 +289,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

tests/test_precedence.py

@@ -1,4 +1,7 @@
-from confidence import Configuration
+import pytest
+
+from confidence import Configuration, Missing, NotConfigured, union
+from confidence.models import NoDefault
 
 
 def test_multiple_sources():
@@ -43,6 +46,19 @@ def test_multiple_overwrite():
     assert subject.namespace.key3 == 3
 
 
+def test_overwrite_multiple_union():
+    subject = original = Configuration({'key1': 1, 'namespace.key1': 1, 'namespace.key2': 2, 'key2': 2})
+    subject |= {'key3': 6, 'namespace.key3': 3}
+
+    # |= should imply an in-place update
+    assert subject is not original
+
+    subject = subject | {'key2': 4, 'key3': 3, 'namespace.key1': 1}
+
+    assert set(subject.keys()) == {'key1', 'namespace', 'key2', 'key3'}
+    assert subject == (original | subject) == union(original, original, subject, subject)
+
+
 def test_overwrite_namespace_with_value():
     subject = Configuration({'key1': 1, 'namespace.key1': 1},
                             {'key2': 2, 'namespace': 'namespace'})
@@ -61,3 +77,24 @@ def test_overwrite_value_with_namespace():
     assert subject.key1 == 1
     assert subject.key2 == 2
     assert subject.namespace.key1 == 1
+
+
+def test_union_settings():
+    source = {'key1': 42, 'key2': True}
+    silent = Configuration(source, missing=Missing.SILENT)
+    error = Configuration(source, missing=Missing.ERROR)
+    value = Configuration(source, missing=5)
+
+    assert union(source, source)._missing is NotConfigured
+    assert union(source, source, missing=Missing.SILENT)._missing is NotConfigured
+    assert (silent | source)._missing is union(silent, source)._missing is NotConfigured
+    assert union(silent, error, value, missing=Missing.ERROR)._missing is NoDefault
+    assert (error | source)._missing is union(error, source)._missing is NoDefault
+    assert (value | source)._missing == union(value,source)._missing == 5
+
+    with pytest.raises(ValueError):
+        assert not union(source, silent, error)
+    with pytest.raises(ValueError):
+        assert not silent | error
+    with pytest.raises(ValueError):
+        assert not value | error