Add freeze / unfreeze methods support to make a benedict instance immutable. #71

Author: fabiocaccamo

README.md

@@ -294,6 +294,8 @@ Here are the details of the supported formats, operations and extra options docs
     -   [`filter`](#filter)
     -   [`find`](#find)
     -   [`flatten`](#flatten)
+    -   [`freeze`](#freeze)
+    -   [`frozen`](#frozen)
     -   [`groupby`](#groupby)
     -   [`invert`](#invert)
     -   [`items_sorted_by_keys`](#items_sorted_by_keys)
@@ -311,6 +313,7 @@ Here are the details of the supported formats, operations and extra options docs
     -   [`swap`](#swap)
     -   [`traverse`](#traverse)
     -   [`unflatten`](#unflatten)
+    -   [`unfreeze`](#unfreeze)
     -   [`unique`](#unique)
 
 -   **I/O methods**
@@ -426,6 +429,22 @@ f = d.find(keys, default=0)
 f = d.flatten(separator="_")
 ```
 
+#### `freeze`
+
+```python
+# Make the dict immutable: any attempt to modify it will raise a TypeError.
+# Only top-level keys are frozen; nested dicts are not affected.
+d.freeze()
+```
+
+#### `frozen`
+
+```python
+# Return True if the dict is frozen (immutable), False otherwise.
+if d.frozen:
+    ...
+```
+
 #### `groupby`
 
 ```python
@@ -564,6 +583,13 @@ d.traverse(f)
 u = d.unflatten(separator="_")
 ```
 
+#### `unfreeze`
+
+```python
+# Make the dict mutable again after a freeze() call.
+d.unfreeze()
+```
+
 #### `unique`
 
 ```python

benedict/dicts/__init__.py

@@ -88,12 +88,15 @@ def __deepcopy__(self, memo: dict[int, Any]) -> Self:
         )
         for key, value in self.items():
             obj[key] = _clone(value, memo=memo)
+        if self._frozen:
+            obj.freeze()
         return obj
 
     def __getitem__(self, key: _KPT) -> Any:  # type: ignore[override]
         return self._cast(super().__getitem__(key))
 
     def __setitem__(self, key: _KPT, value: _V) -> None:  # type: ignore[override]
+        self._check_frozen()
         super().__setitem__(key, self._cast(value))
 
     def _cast(self, value: Any) -> Any:
@@ -133,7 +136,17 @@ def copy(self) -> Self:
         """
         Creates and return a copy of the current instance (shallow copy).
         """
-        return cast("Self", self._cast(super().copy()))
+        obj_type = type(self)
+        obj = obj_type(
+            keyattr_enabled=self._keyattr_enabled,
+            keyattr_dynamic=self._keyattr_dynamic,
+            keypath_separator=self._keypath_separator,
+        )
+        for key, value in self.items():
+            obj[key] = value
+        if self._frozen:
+            obj.freeze()
+        return obj
 
     def deepcopy(self) -> Self:
         """

benedict/dicts/base/base_dict.py

@@ -19,7 +19,8 @@
 
 
 class BaseDict(dict[_K, _V]):
-    _dict: dict[_K, _V] | None = None
+    _dict: dict[_K, _V] | None
+    _frozen: bool
 
     @classmethod
     def _get_dict_or_value(cls, value: Any) -> Any:
@@ -32,11 +33,19 @@ def _get_dict_or_value(cls, value: Any) -> Any:
                     value[key] = key_val
         return value
 
+    def __new__(cls, *args: Any, **kwargs: Any) -> Self:
+        obj = super().__new__(cls)
+        # bypass subclass __setattr__ (e.g. KeyattrDict) which may access _dict before it exists
+        object.__setattr__(obj, "_dict", None)
+        object.__setattr__(obj, "_frozen", False)
+        return obj
+
     def __init__(self, *args: Any, **kwargs: Any) -> None:
-        self._dict = None
         if len(args) == 1 and isinstance(args[0], Mapping):
-            self._dict = self._get_dict_or_value(args[0])
-            super().__init__(self._dict)
+            # bypass subclass __setattr__ (e.g. KeyattrDict) which may treat _dict as a key
+            d = self._get_dict_or_value(args[0])
+            object.__setattr__(self, "_dict", d)
+            super().__init__(d)
             return
         super().__init__(*args, **kwargs)
 
@@ -54,9 +63,12 @@ def __deepcopy__(self, memo: dict[int, Any]) -> Self:
         obj = self.__class__()
         for key, value in self.items():
             obj[key] = _clone(value, memo=memo)
+        if self._frozen:
+            obj.freeze()
         return obj
 
     def __delitem__(self, key: _K) -> None:
+        self._check_frozen()
         if self._dict is not None:
             del self._dict[key]
             return
@@ -73,6 +85,7 @@ def __getitem__(self, key: _K) -> _V:
         return super().__getitem__(key)
 
     def __ior__(self, other: Any) -> Self:  # type: ignore[misc,override]
+        self._check_frozen()
         if self._dict is not None:
             return cast("Self", self._dict.__ior__(other))
         return super().__ior__(other)
@@ -98,6 +111,7 @@ def __repr__(self) -> str:
         return super().__repr__()
 
     def __setitem__(self, key: _K, value: _V) -> None:
+        self._check_frozen()
         value = self._get_dict_or_value(value)
         if self._dict is not None:
             is_dict_item = key in self._dict and isinstance(self._dict[key], dict)
@@ -114,24 +128,46 @@ def __setitem__(self, key: _K, value: _V) -> None:
         super().__setitem__(key, value)
 
     def __setstate__(self, state: Mapping[str, Any]) -> None:
-        self._dict = state["_dict"]
-        self._dict = state["_dict"]
+        object.__setattr__(self, "_dict", state.get("_dict", None))
+        object.__setattr__(self, "_frozen", state.get("_frozen", False))
 
     def __str__(self) -> str:
         if self._dict is not None:
             return str(self._dict)
         return super().__str__()
 
+    def _check_frozen(self) -> None:
+        if self._frozen:
+            raise TypeError(
+                f"{self.__class__.__name__!r} object is frozen and cannot be modified."
+            )
+
+    @property
+    def frozen(self) -> bool:
+        return self._frozen
+
+    def freeze(self) -> Self:
+        object.__setattr__(self, "_frozen", True)
+        return self
+
+    def unfreeze(self) -> Self:
+        object.__setattr__(self, "_frozen", False)
+        return self
+
     def clear(self) -> None:
+        self._check_frozen()
         if self._dict is not None:
             self._dict.clear()
             return
         super().clear()
 
     def copy(self) -> Self:
-        if self._dict is not None:
-            return cast("Self", self._dict.copy())
-        return cast("Self", super().copy())
+        obj = self.__class__()
+        for key, value in self.items():
+            obj[key] = value
+        if self._frozen:
+            obj.freeze()
+        return obj
 
     def dict(self) -> Self:
         if self._dict is not None:
@@ -154,18 +190,21 @@ def keys(self) -> KeysView[_K]:  # type: ignore[override]
         return super().keys()
 
     def pop(self, key: _K, *args: Any) -> _V:
+        self._check_frozen()
         if self._dict is not None:
             return self._dict.pop(key, *args)  # type: ignore[no-any-return]
         return super().pop(key, *args)  # type: ignore[no-any-return]
 
     def setdefault(self, key: _K, default: _V | None = None) -> _V:
+        self._check_frozen()
         default = self._get_dict_or_value(default)
         assert default is not None
         if self._dict is not None:
             return self._dict.setdefault(key, default)
         return super().setdefault(key, default)
 
     def update(self, other: Any) -> None:
+        self._check_frozen()
         other = self._get_dict_or_value(other)
         if self._dict is not None:
             self._dict.update(other)

tests/dicts/base/test_base_dict_freeze.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+import copy
+import unittest
+
+from benedict.dicts.base import BaseDict
+
+
+class base_dict_freeze_test_case(unittest.TestCase):
+    def test_freeze(self) -> None:
+        b = BaseDict({"a": 1})
+        self.assertFalse(b.frozen)
+        b.freeze()
+        self.assertTrue(b.frozen)
+
+    def test_freeze_returns_self(self) -> None:
+        b = BaseDict({"a": 1})
+        self.assertIs(b.freeze(), b)
+
+    def test_freeze_prevents_setitem(self) -> None:
+        b = BaseDict({"a": 1})
+        b.freeze()
+        with self.assertRaises(TypeError):
+            b["a"] = 2
+        with self.assertRaises(TypeError):
+            b["b"] = 3
+
+    def test_freeze_prevents_delitem(self) -> None:
+        b = BaseDict({"a": 1})
+        b.freeze()
+        with self.assertRaises(TypeError):
+            del b["a"]
+
+    def test_freeze_prevents_clear(self) -> None:
+        b = BaseDict({"a": 1})
+        b.freeze()
+        with self.assertRaises(TypeError):
+            b.clear()
+
+    def test_freeze_prevents_pop(self) -> None:
+        b = BaseDict({"a": 1})
+        b.freeze()
+        with self.assertRaises(TypeError):
+            b.pop("a")
+
+    def test_freeze_prevents_setdefault(self) -> None:
+        b = BaseDict({"a": 1})
+        b.freeze()
+        with self.assertRaises(TypeError):
+            b.setdefault("b", 2)
+
+    def test_freeze_prevents_update(self) -> None:
+        b = BaseDict({"a": 1})
+        b.freeze()
+        with self.assertRaises(TypeError):
+            b.update({"b": 2})
+
+    def test_freeze_allows_read(self) -> None:
+        b = BaseDict({"a": 1, "b": 2})
+        b.freeze()
+        self.assertEqual(b["a"], 1)
+        self.assertIn("a", b)
+        self.assertEqual(list(b.keys()), ["a", "b"])
+
+    def test_unfreeze(self) -> None:
+        b = BaseDict({"a": 1})
+        b.freeze()
+        self.assertTrue(b.frozen)
+        b.unfreeze()
+        self.assertFalse(b.frozen)
+
+    def test_unfreeze_returns_self(self) -> None:
+        b = BaseDict({"a": 1})
+        self.assertIs(b.freeze().unfreeze(), b)
+
+    def test_unfreeze_allows_setitem(self) -> None:
+        b = BaseDict({"a": 1})
+        b.freeze()
+        b.unfreeze()
+        b["a"] = 2
+        self.assertEqual(b["a"], 2)
+
+    def test_freeze_does_not_propagate_to_nested_dict(self) -> None:
+        # freeze() only blocks top-level mutations (aligned with frozendict/MappingProxyType).
+        # nested dicts are not frozen.
+        b = BaseDict({"a": 1, "b": {"c": 2}})
+        b.freeze()
+        self.assertTrue(b.frozen)
+        with self.assertRaises(TypeError):
+            b["a"] = 99
+
+    def test_freeze_does_not_propagate_to_dict_in_list(self) -> None:
+        inner = BaseDict({"b": 1})
+        b = BaseDict()
+        super(BaseDict, b).__setitem__("a", [inner])  # type: ignore[call-arg]
+        b.freeze()
+        # top-level is frozen
+        self.assertTrue(b.frozen)
+        # nested BaseDict is NOT frozen (no deep propagation)
+        self.assertFalse(inner.frozen)
+
+    def test_unfreeze_allows_setitem_after_freeze(self) -> None:
+        b = BaseDict({"a": 1})
+        b.freeze()
+        self.assertTrue(b.frozen)
+        b.unfreeze()
+        self.assertFalse(b.frozen)
+        b["a"] = 2
+        self.assertEqual(b["a"], 2)
+
+    def test_copy_of_frozen_is_frozen(self) -> None:
+        b = BaseDict({"a": 1})
+        b.freeze()
+        c = b.copy()
+        self.assertTrue(c.frozen)
+        with self.assertRaises(TypeError):
+            c["a"] = 2
+
+    def test_copy_of_unfrozen_is_not_frozen(self) -> None:
+        b = BaseDict({"a": 1})
+        c = b.copy()
+        self.assertFalse(c.frozen)
+        c["a"] = 2  # must not raise
+
+    def test_deepcopy_of_frozen_is_frozen(self) -> None:
+        b = BaseDict({"a": 1})
+        b.freeze()
+        c = copy.deepcopy(b)
+        self.assertTrue(c.frozen)
+        with self.assertRaises(TypeError):
+            c["a"] = 2
+
+    def test_deepcopy_of_unfrozen_is_not_frozen(self) -> None:
+        b = BaseDict({"a": 1})
+        c = copy.deepcopy(b)
+        self.assertFalse(c.frozen)
+        c["a"] = 2  # must not raise