Add get_freezable, unset_freezable, and FreezabilityOverride context … (#89)

* Add get_freezable, unset_freezable, and FreezabilityOverride context manager

Add C-level get_freezable() and unset_freezable() functions to query and
clear per-object freezability status, and a Python-level
FreezabilityOverride context manager that temporarily overrides an
object's freezability.

C API changes (Python/immutability.c, Include/cpython/immutability.h):

  - _PyImmutability_GetFreezable(obj): returns the effective freezable
    status (checking object, then ob_flags, then type, then type's
    ob_flags).  Returns -1 if unset, -2 on error.

  - _PyImmutability_UnsetFreezable(obj): removes any per-object
    freezable status by deleting __freezable__ and clearing ob_flags.
    Includes a failing assert on 32-bit for the ob_flags path, matching
    the pattern in SetFreezable.

Module changes (Modules/_immutablemodule.c):

  - Expose get_freezable() and unset_freezable() via Argument Clinic.

Python changes (Lib/immutable.py):

  - Export get_freezable and unset_freezable.

  - Add FreezabilityOverride context manager.  On enter, snapshots the
    effective status via get_freezable() and applies the override.  On
    exit, restores the saved status via set_freezable().

    Uses a "no-effort unset" design: always restores the effective status
    that was observed on entry, even if it was inherited from the type.
    This may leave an explicit per-object status where none existed
    before, but is simple, predictable, and correct for all object kinds
    including C types with custom tp_getattro.  The alternative
    "best-effort unset" approach (using a get_direct_freezable that
    inspects __dict__ directly) was explored and rejected because it
    cannot reliably distinguish per-object from inherited status for
    C extension types with custom attribute storage.

Tests (Lib/test/test_freeze/):

  - test_get_freezable.py: tests for get_freezable() (7 tests) and
    unset_freezable() (5 tests).

  - test_freezability_override.py: tests for FreezabilityOverride
    (10 tests) covering basic override/restore, freeze prevention,
    freeze allowance, exception safety, nested overrides, class-level
    override, and the no-effort unset behavior.

* Lint fix.

* Add version from paper.

Author: mjp41

Include/cpython/immutability.h

@@ -15,3 +15,4 @@ PyAPI_FUNC(int) _PyImmutability_RegisterShallowImmutable(PyTypeObject*);
 PyAPI_FUNC(int) _PyImmutability_CanViewAsImmutable(PyObject*);
 PyAPI_FUNC(int) _PyImmutability_SetFreezable(PyObject *, _Py_freezable_status);
 PyAPI_FUNC(int) _PyImmutability_GetFreezable(PyObject *);
+PyAPI_FUNC(int) _PyImmutability_UnsetFreezable(PyObject *);

Lib/immutable.py

@@ -11,6 +11,8 @@
 freeze = _c.freeze
 is_frozen = _c.is_frozen
 set_freezable = _c.set_freezable
+get_freezable = _c.get_freezable
+unset_freezable = _c.unset_freezable
 NotFreezableError = _c.NotFreezableError
 ImmutableModule = _c.ImmutableModule
 FREEZABLE_YES = _c.FREEZABLE_YES
@@ -50,6 +52,79 @@ def frozen(cls):
     return cls
 
 
+class FreezabilityOverride:
+    """Context manager to temporarily override an object's freezability.
+
+    On entry, saves the object's current effective freezability (which may
+    be inherited from the type) and applies the requested override.
+    On exit, restores the saved status via set_freezable().
+
+    Design note: on exit we always call set_freezable() with the value
+    that get_freezable() returned on entry, even if that value was
+    inherited from the type rather than set directly on the object.
+    This means the context manager may leave a per-object status where
+    none existed before.  We considered two alternatives:
+
+      * "Best-effort unset": use a get_direct_freezable() that inspects
+        only the object's own __dict__ / ob_flags, and call
+        unset_freezable() when no direct status existed.  This mostly
+        works, but C types with custom tp_getattro cannot reliably
+        distinguish per-object from inherited status, so the "direct"
+        check is incomplete for some extension types.
+
+      * "No-effort unset" (chosen): always snapshot the effective status
+        and restore it with set_freezable().  Simple, correct for all
+        object kinds, and predictable.  The trade-off is that after the
+        context manager exits, the object will have an explicit
+        per-object status even if it previously relied on inheritance.
+
+    Usage:
+        with FreezabilityOverride(obj, FREEZABLE_NO):
+            # obj is temporarily not freezable
+            ...
+        # obj's original effective freezability is restored
+    """
+
+    def __init__(self, obj, status):
+        self._obj = obj
+        self._new_status = status
+        self._old_status = None
+
+    def __enter__(self):
+        self._old_status = get_freezable(self._obj)
+        set_freezable(self._obj, self._new_status)
+        return self._obj
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if self._old_status == -1:
+            # No status was set anywhere (not on object, not on type).
+            # Restore to the default: FREEZABLE_YES.
+            set_freezable(self._obj, FREEZABLE_YES)
+        else:
+            set_freezable(self._obj, self._old_status)
+        return False
+
+
+class require_mutable(FreezabilityOverride):
+    """Context manager that ensures an object remains mutable (not freezable).
+
+    Raises TypeError if the object is already frozen.
+
+    Usage:
+        with require_mutable(obj):
+            obj.attr = value  # guaranteed not to be frozen during this block
+    """
+
+    def __init__(self, obj):
+        super().__init__(obj, FREEZABLE_NO)
+
+    def __enter__(self):
+        if is_frozen(self._obj):
+            raise TypeError(
+                "cannot require mutability: object is already frozen")
+        return super().__enter__()
+
+
 __all__ = [
     "freeze",
     "is_frozen",

Lib/test/test_freeze/test_freezability_override.py

@@ -0,0 +1,158 @@
+"""Tests for FreezabilityOverride and require_mutable context managers."""
+
+import unittest
+from immutable import (
+    freeze, is_frozen, set_freezable, get_freezable,
+    FreezabilityOverride, require_mutable,
+    FREEZABLE_YES, FREEZABLE_NO, FREEZABLE_EXPLICIT,
+)
+
+
+def make_freezable_class():
+    """Create a fresh class marked as freezable."""
+    class C:
+        pass
+    set_freezable(C, FREEZABLE_YES)
+    return C
+
+
+class TestFreezabilityOverride(unittest.TestCase):
+    """Tests for the FreezabilityOverride context manager."""
+
+    def test_basic_override_and_restore(self):
+        C = make_freezable_class()
+        obj = C()
+        set_freezable(obj, FREEZABLE_YES)
+        with FreezabilityOverride(obj, FREEZABLE_NO):
+            self.assertEqual(get_freezable(obj), FREEZABLE_NO)
+        self.assertEqual(get_freezable(obj), FREEZABLE_YES)
+
+    def test_override_prevents_freeze(self):
+        C = make_freezable_class()
+        obj = C()
+        set_freezable(obj, FREEZABLE_YES)
+        with FreezabilityOverride(obj, FREEZABLE_NO):
+            with self.assertRaises(TypeError):
+                freeze(obj)
+        # After the context manager, freezing should work again.
+        freeze(obj)
+        self.assertTrue(is_frozen(obj))
+
+    def test_override_allows_freeze(self):
+        C = make_freezable_class()
+        obj = C()
+        set_freezable(obj, FREEZABLE_NO)
+        with FreezabilityOverride(obj, FREEZABLE_YES):
+            freeze(obj)
+            self.assertTrue(is_frozen(obj))
+
+    def test_override_to_explicit(self):
+        C = make_freezable_class()
+        obj = C()
+        set_freezable(obj, FREEZABLE_YES)
+        with FreezabilityOverride(obj, FREEZABLE_EXPLICIT):
+            self.assertEqual(get_freezable(obj), FREEZABLE_EXPLICIT)
+        self.assertEqual(get_freezable(obj), FREEZABLE_YES)
+
+    def test_restores_on_exception(self):
+        C = make_freezable_class()
+        obj = C()
+        set_freezable(obj, FREEZABLE_YES)
+        with self.assertRaises(RuntimeError):
+            with FreezabilityOverride(obj, FREEZABLE_NO):
+                self.assertEqual(get_freezable(obj), FREEZABLE_NO)
+                raise RuntimeError("deliberate")
+        # Status should be restored even after an exception.
+        self.assertEqual(get_freezable(obj), FREEZABLE_YES)
+
+    def test_returns_obj_from_enter(self):
+        C = make_freezable_class()
+        obj = C()
+        set_freezable(obj, FREEZABLE_YES)
+        with FreezabilityOverride(obj, FREEZABLE_NO) as returned:
+            self.assertIs(returned, obj)
+
+    def test_no_prior_status_restores_default(self):
+        C = make_freezable_class()
+        obj = C()
+        # Object inherits YES from type, no per-object status.
+        self.assertEqual(get_freezable(obj), FREEZABLE_YES)
+        with FreezabilityOverride(obj, FREEZABLE_NO):
+            self.assertEqual(get_freezable(obj), FREEZABLE_NO)
+        # The inherited YES is restored (now set explicitly on the
+        # object — this is the "no-effort unset" design choice).
+        self.assertEqual(get_freezable(obj), FREEZABLE_YES)
+
+    def test_no_status_anywhere_restores_yes(self):
+        class C:
+            pass
+        obj = C()
+        self.assertEqual(get_freezable(obj), -1)
+        with FreezabilityOverride(obj, FREEZABLE_NO):
+            self.assertEqual(get_freezable(obj), FREEZABLE_NO)
+        # When no status existed anywhere, restores to FREEZABLE_YES.
+        self.assertEqual(get_freezable(obj), FREEZABLE_YES)
+
+    def test_nested_overrides(self):
+        C = make_freezable_class()
+        obj = C()
+        set_freezable(obj, FREEZABLE_YES)
+        with FreezabilityOverride(obj, FREEZABLE_NO):
+            self.assertEqual(get_freezable(obj), FREEZABLE_NO)
+            with FreezabilityOverride(obj, FREEZABLE_EXPLICIT):
+                self.assertEqual(get_freezable(obj), FREEZABLE_EXPLICIT)
+            self.assertEqual(get_freezable(obj), FREEZABLE_NO)
+        self.assertEqual(get_freezable(obj), FREEZABLE_YES)
+
+    def test_override_on_class(self):
+        C = make_freezable_class()
+        self.assertEqual(get_freezable(C), FREEZABLE_YES)
+        with FreezabilityOverride(C, FREEZABLE_NO):
+            self.assertEqual(get_freezable(C), FREEZABLE_NO)
+        self.assertEqual(get_freezable(C), FREEZABLE_YES)
+
+
+class TestRequireMutable(unittest.TestCase):
+    """Tests for the require_mutable context manager."""
+
+    def test_sets_freezable_no(self):
+        C = make_freezable_class()
+        obj = C()
+        set_freezable(obj, FREEZABLE_YES)
+        with require_mutable(obj):
+            self.assertEqual(get_freezable(obj), FREEZABLE_NO)
+        self.assertEqual(get_freezable(obj), FREEZABLE_YES)
+
+    def test_prevents_freeze_inside(self):
+        C = make_freezable_class()
+        obj = C()
+        with require_mutable(obj):
+            with self.assertRaises(TypeError):
+                freeze(obj)
+
+    def test_raises_if_already_frozen(self):
+        C = make_freezable_class()
+        obj = C()
+        freeze(obj)
+        with self.assertRaises(TypeError):
+            with require_mutable(obj):
+                pass  # should never reach here
+
+    def test_restores_on_exception(self):
+        C = make_freezable_class()
+        obj = C()
+        set_freezable(obj, FREEZABLE_YES)
+        with self.assertRaises(RuntimeError):
+            with require_mutable(obj):
+                raise RuntimeError("deliberate")
+        self.assertEqual(get_freezable(obj), FREEZABLE_YES)
+
+    def test_returns_obj_from_enter(self):
+        C = make_freezable_class()
+        obj = C()
+        with require_mutable(obj) as returned:
+            self.assertIs(returned, obj)
+
+
+if __name__ == '__main__':
+    unittest.main()

Lib/test/test_freeze/test_get_freezable.py

@@ -0,0 +1,119 @@
+"""Tests for get_freezable() and unset_freezable()."""
+
+import unittest
+from immutable import (
+    set_freezable, get_freezable, unset_freezable,
+    FREEZABLE_YES, FREEZABLE_NO, FREEZABLE_EXPLICIT,
+)
+
+
+def make_freezable_class():
+    """Create a fresh class marked as freezable."""
+    class C:
+        pass
+    set_freezable(C, FREEZABLE_YES)
+    return C
+
+
+class TestGetFreezable(unittest.TestCase):
+    """Tests for get_freezable()."""
+
+    def test_no_status_set_returns_negative_one(self):
+        class C:
+            pass
+        self.assertEqual(get_freezable(C()), -1)
+
+    def test_returns_yes(self):
+        C = make_freezable_class()
+        obj = C()
+        set_freezable(obj, FREEZABLE_YES)
+        self.assertEqual(get_freezable(obj), FREEZABLE_YES)
+
+    def test_returns_no(self):
+        C = make_freezable_class()
+        obj = C()
+        set_freezable(obj, FREEZABLE_NO)
+        self.assertEqual(get_freezable(obj), FREEZABLE_NO)
+
+    def test_returns_explicit(self):
+        C = make_freezable_class()
+        obj = C()
+        set_freezable(obj, FREEZABLE_EXPLICIT)
+        self.assertEqual(get_freezable(obj), FREEZABLE_EXPLICIT)
+
+    def test_reflects_override(self):
+        C = make_freezable_class()
+        obj = C()
+        set_freezable(obj, FREEZABLE_YES)
+        self.assertEqual(get_freezable(obj), FREEZABLE_YES)
+        set_freezable(obj, FREEZABLE_NO)
+        self.assertEqual(get_freezable(obj), FREEZABLE_NO)
+
+    def test_type_level_status(self):
+        C = make_freezable_class()
+        # The class has FREEZABLE_YES; an instance with no per-object
+        # status should inherit from the type.
+        obj = C()
+        self.assertEqual(get_freezable(obj), FREEZABLE_YES)
+
+    def test_object_status_overrides_type(self):
+        C = make_freezable_class()
+        obj = C()
+        set_freezable(obj, FREEZABLE_NO)
+        # Per-object status should take precedence over the type's.
+        self.assertEqual(get_freezable(obj), FREEZABLE_NO)
+        # The type itself should still be YES.
+        self.assertEqual(get_freezable(C), FREEZABLE_YES)
+
+
+class TestUnsetFreezable(unittest.TestCase):
+    """Tests for unset_freezable()."""
+
+    def test_unset_removes_per_object_status(self):
+        C = make_freezable_class()
+        obj = C()
+        set_freezable(obj, FREEZABLE_NO)
+        self.assertEqual(get_freezable(obj), FREEZABLE_NO)
+        unset_freezable(obj)
+        # Falls back to the type's status (FREEZABLE_YES).
+        self.assertEqual(get_freezable(obj), FREEZABLE_YES)
+
+    def test_unset_when_nothing_set(self):
+        class C:
+            pass
+        obj = C()
+        # Should not raise even if nothing was set.
+        unset_freezable(obj)
+        self.assertEqual(get_freezable(obj), -1)
+
+    def test_unset_reveals_type_status(self):
+        C = make_freezable_class()
+        obj = C()
+        set_freezable(obj, FREEZABLE_EXPLICIT)
+        self.assertEqual(get_freezable(obj), FREEZABLE_EXPLICIT)
+        unset_freezable(obj)
+        # Now the type's YES should show through.
+        self.assertEqual(get_freezable(obj), FREEZABLE_YES)
+
+    def test_unset_on_class(self):
+        class C:
+            pass
+        set_freezable(C, FREEZABLE_NO)
+        self.assertEqual(get_freezable(C), FREEZABLE_NO)
+        unset_freezable(C)
+        # After unsetting, falls back to the metaclass (type) status.
+        # type may or may not have __freezable__ set depending on
+        # interpreter state, so just verify it's no longer NO.
+        self.assertNotEqual(get_freezable(C), FREEZABLE_NO)
+
+    def test_unset_then_set_again(self):
+        C = make_freezable_class()
+        obj = C()
+        set_freezable(obj, FREEZABLE_NO)
+        unset_freezable(obj)
+        set_freezable(obj, FREEZABLE_EXPLICIT)
+        self.assertEqual(get_freezable(obj), FREEZABLE_EXPLICIT)
+
+
+if __name__ == '__main__':
+    unittest.main()