Add "raw" keyword-only parameter to Loader.get_settings()

CONTRIBUTORS.txt

@@ -108,3 +108,4 @@ Contributors
 - Michael Merickel (2016-06-12)
 - Steve Piercy (2017-08-31)
 - Bert JW Regeer (2019-05-31)
+- Karl O. Pinc (2024-04-14)

docs/index.rst

@@ -176,15 +176,15 @@ If the loader should be found automatically via file extension then it should br
         def get_sections(self):
             return ['myapp', 'yourapp']
 
-        def get_settings(self, section=None, defaults=None):
+        def get_settings(self, section=None, defaults=None, raw=False):
             # fallback to the fragment from config_uri if no section is given
             if not section:
                 section = self.uri.fragment
             # if section is still none we could fallback to some
             # loader-specific default
 
             result = {}
-            if defaults is not None:
+            if not raw and defaults is not None:
                 result.update(defaults)
             if section == 'myapp':
                 result.update({'a': 1})

src/plaster/interfaces.py

@@ -29,7 +29,7 @@ def get_sections(self):
         """
 
     @abc.abstractmethod
-    def get_settings(self, section=None, defaults=None):
+    def get_settings(self, section=None, defaults=None, *, raw=False):
         """
         Load the settings for the named ``section``.
 
@@ -43,6 +43,9 @@ def get_settings(self, section=None, defaults=None):
             ``defaults`` may be overridden by the loader prior to returning
             the final configuration dictionary.
 
+        :param raw: when not True, return the section without interpolation,
+            application of defaults, or other alteration.
+
         :returns: A ``dict`` of settings. This should return a dictionary
             object even if the section is missing.
         :raises ValueError: If a section name is missing and cannot be

src/plaster/loaders.py

@@ -31,7 +31,7 @@ def get_sections(config_uri):
     return loader.get_sections()
 
 
-def get_settings(config_uri, section=None, defaults=None):
+def get_settings(config_uri, section=None, defaults=None, *, raw=False):
     """
     Load the settings from a named section.
 
@@ -53,13 +53,16 @@ def get_settings(config_uri, section=None, defaults=None):
         may be overridden by the loader prior to returning the final
         configuration dictionary.
 
+    :param raw: when not True, return the section without interpolation,
+        application of defaults, or other alteration.
+
     :returns: A ``dict`` of settings. This should return a dictionary object
         even if no data is available.
 
     """
     loader = get_loader(config_uri)
 
-    return loader.get_settings(section, defaults)
+    return loader.get_settings(section, defaults, raw=raw)
 
 
 def setup_logging(config_uri, defaults=None):

tests/fake_packages/app1/app1/loaders.py

@@ -13,10 +13,10 @@ def __init__(self, uri):
     def get_sections(self):
         return list(_SECTIONS.keys())
 
-    def get_settings(self, section=None, defaults=None):
+    def get_settings(self, section=None, defaults=None, *, raw=False):
         if section is None:
             section = self.uri.fragment
-        if defaults is not None:
+        if defaults is not None and not raw:
             result = defaults.copy()
         else:
             result = {}

tests/fake_packages/app2/app2/loaders.py

@@ -12,10 +12,10 @@ def __init__(self, uri):
     def get_sections(self):
         return list(_SECTIONS.keys())
 
-    def get_settings(self, section=None, defaults=None):
+    def get_settings(self, section=None, defaults=None, *, raw=False):
         if section is None:
             section = self.uri.fragment
-        if defaults is not None:
+        if defaults is not None and not raw:
             result = defaults.copy()
         else:
             result = {}

tests/test_loaders.py

@@ -141,36 +141,40 @@ def test_it_bad(self):
             self._callFUT("development.bad")
 
 
+@pytest.mark.parametrize("raw", [False, True])
 @pytest.mark.usefixtures("fake_packages")
 class Test_get_settings:
-    def _callFUT(self, config_uri, section=None, defaults=None):
+    def _callFUT(self, config_uri, section=None, defaults=None, *, raw=False):
         from plaster.loaders import get_settings
 
-        return get_settings(config_uri, section=section, defaults=defaults)
+        return get_settings(config_uri, section=section, defaults=defaults, raw=raw)
 
-    def test_it_explicit_a(self):
-        result = self._callFUT("development.ini", "a")
+    def test_it_explicit_a(self, raw):
+        result = self._callFUT("development.ini", "a", raw=raw)
         assert result == {"foo": "bar"}
 
-    def test_it_explicit_b(self):
-        result = self._callFUT("development.ini", "b")
+    def test_it_explicit_b(self, raw):
+        result = self._callFUT("development.ini", "b", raw=raw)
         assert result == {"baz": "xyz"}
 
-    def test_it_fragment(self):
-        result = self._callFUT("development.ini#a")
+    def test_it_fragment(self, raw):
+        result = self._callFUT("development.ini#a", raw=raw)
         assert result == {"foo": "bar"}
 
-    def test_defaults(self):
-        result = self._callFUT("development.ini", "a", {"baz": "foo"})
-        assert result == {"foo": "bar", "baz": "foo"}
+    def test_defaults(self, raw):
+        result = self._callFUT("development.ini", "a", {"baz": "foo"}, raw=raw)
+        if raw:
+            assert result == {"foo": "bar"}
+        else:
+            assert result == {"foo": "bar", "baz": "foo"}
 
-    def test_invalid_section(self):
-        result = self._callFUT("development.ini", "c")
+    def test_invalid_section(self, raw):
+        result = self._callFUT("development.ini", "c", raw=raw)
         assert result == {}
 
-    def test_it_bad(self):
+    def test_it_bad(self, raw):
         with pytest.raises(Exception):
-            self._callFUT("development.bad")
+            self._callFUT("development.bad", raw=raw)
 
 
 @pytest.mark.usefixtures("fake_packages")