Support dunder keys (#21)

Author: stevebachmeier

CHANGELOG.rst

@@ -1,3 +1,7 @@
+**3.0.0 - 02/18/2025**
+
+ - Better handle dunder-style keys
+
 **2.2.1 - 12/27/2024**
 
  - Bugfix: failing mypy

src/layered_config_tree/__init__.py

@@ -12,5 +12,6 @@
     ConfigurationError,
     ConfigurationKeyError,
     DuplicatedConfigurationError,
+    ImproperAccessError,
 )
 from layered_config_tree.main import ConfigNode, LayeredConfigTree

src/layered_config_tree/exceptions.py

@@ -15,6 +15,12 @@ class ConfigurationKeyError(ConfigurationError, KeyError):
     pass
 
 
+class ImproperAccessError(ConfigurationError):
+    """Error raised when a configuration value is accessed improperly."""
+
+    pass
+
+
 class DuplicatedConfigurationError(ConfigurationError):
     """Error raised when a configuration value is set more than once.
 

src/layered_config_tree/main.py

@@ -39,6 +39,7 @@
     ConfigurationError,
     ConfigurationKeyError,
     DuplicatedConfigurationError,
+    ImproperAccessError,
 )
 from layered_config_tree.types import InputData
 
@@ -548,12 +549,26 @@ def _set_with_metadata(
         self._children[name].update(value, layer, source)
 
     def __setattr__(self, name: str, value: Any) -> None:
-        """Set a value on the outermost layer."""
+        """Set a value on the outermost layer.
+
+        Notes
+        -----
+        We allow keys that look like dunder attributes, i.e. start and end with
+        "__". However, to avoid conflict with actual dunder methods and attributes,
+        we do not allow setting them via this method and instead require dictionary
+        access (i.e. bracket notation).
+        """
         if name not in self:
             raise ConfigurationKeyError(
                 "New configuration keys can only be created with the update method.",
                 self._name,
             )
+        if name.startswith("__") and name.endswith("__"):
+            raise ImproperAccessError(
+                "Cannot set an attribute starting and ending with '__' via attribute "
+                "access (i.e. dot notation). Use dictionary access instead "
+                "(i.e. bracket notation)."
+            )
         self._set_with_metadata(name, value, layer=None, source=None)
 
     def __setitem__(self, name: str, value: Any) -> None:
@@ -566,10 +581,35 @@ def __setitem__(self, name: str, value: Any) -> None:
         self._set_with_metadata(name, value, layer=None, source=None)
 
     # FIXME: We expect the return to be a ConfigNode or LayeredConfigTree but
-    # the type checker doesn't know what you're getting back in chained
-    # attribute calls. We return Any as a workaround.
+    # static type checkers don't know what you're getting back in chained
+    # attribute calls. We type hint returning Any as a workaround.
     def __getattr__(self, name: str) -> Any:
-        """Get a value from the outermost layer in which it appears."""
+        """Get a value from the outermost layer in which it appears.
+
+        Notes
+        -----
+        We allow keys that look like dunder attributes, i.e. start and end with
+        "__". However, to avoid conflict with actual dunder methods and attributes,
+        we do not allow getting them via this method and instead require dictionary
+        access (i.e. bracket notation).
+
+        If the requested attribute starts and ends with "__" but *does not* actually
+        exist, it is critical that we raise an AttributeError since some functions
+        specifically handle it, e.g. ``pickle`` and ``copy.deepcopy``.
+        See https://stackoverflow.com/a/50888571/
+
+        One the other hand, if the requested attribute starts and ends with "__"
+        and *does* exist, it is critical that we raise a non-AttributeError exception
+        so as not to conflict with dunder methods and attributes.
+        """
+        if name.startswith("__") and name.endswith("__"):
+            if name not in self:
+                raise AttributeError  # Do not change from AttributeError
+            raise ImproperAccessError(
+                "Cannot get an attribute starting and ending with '__' via attribute "
+                "access (i.e. dot notation). Use dictionary access instead "
+                "(i.e. bracket notation)."
+            )
         return self.get_from_layer(name)
 
     # We need custom definitions of __getstate__ and __setstate__

tests/test_basic_functionality.py

@@ -1,4 +1,5 @@
 import pickle
+import re
 import textwrap
 from pathlib import Path
 from typing import Any
@@ -11,6 +12,7 @@
     ConfigurationError,
     ConfigurationKeyError,
     DuplicatedConfigurationError,
+    ImproperAccessError,
     LayeredConfigTree,
 )
 
@@ -343,6 +345,40 @@ def test_dictionary_style_access() -> None:
     assert lct["test_key"] == "test_value"
 
 
+def test_dunder_key_attr_style_access() -> None:
+    lct = LayeredConfigTree({"__dunder_key__": "val"}, layers=["layer1", "layer2"])
+    # lct.update({"__dunder_key__": "val"})
+    assert lct["__dunder_key__"] == "val"
+
+    with pytest.raises(
+        ImproperAccessError,
+        match=re.escape(
+            "Cannot get an attribute starting and ending with '__' via attribute "
+            "access (i.e. dot notation). Use dictionary access instead "
+            "(i.e. bracket notation)."
+        ),
+    ):
+        lct.__dunder_key__
+
+    with pytest.raises(
+        ImproperAccessError,
+        match=re.escape(
+            "Cannot set an attribute starting and ending with '__' via attribute "
+            "access (i.e. dot notation). Use dictionary access instead "
+            "(i.e. bracket notation)."
+        ),
+    ):
+        lct.__dunder_key__ = "val2"
+    assert lct["__dunder_key__"] == "val"
+
+    # check that we can modify the value in a new layer
+    lct["__dunder_key__"] = "val2"
+    assert lct["__dunder_key__"] == "val2"
+
+    with pytest.raises(AttributeError):
+        lct.__non_existent_dunder_key__
+
+
 def test_get_missing_key() -> None:
     lct = LayeredConfigTree()
     with pytest.raises(ConfigurationKeyError):
@@ -351,9 +387,12 @@ def test_get_missing_key() -> None:
 
 def test_set_missing_key() -> None:
     lct = LayeredConfigTree()
-    with pytest.raises(ConfigurationKeyError):
+    error_msg = re.escape(
+        "New configuration keys can only be created with the update method."
+    )
+    with pytest.raises(ConfigurationKeyError, match=error_msg):
         lct.missing_key = "test_value"
-    with pytest.raises(ConfigurationKeyError):
+    with pytest.raises(ConfigurationKeyError, match=error_msg):
         lct["missing_key"] = "test_value"