WIP: Custom frozen dataclasses

Author: tony

src/libtmux/_internal/frozen_dataclass.py

@@ -0,0 +1,76 @@
+"""Custom frozen dataclass implementation that works with inheritance.
+
+This module provides a `frozen_dataclass` decorator that allows creating
+effectively immutable dataclasses that can inherit from mutable ones,
+which is not possible with standard dataclasses.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import typing as t
+
+from typing_extensions import dataclass_transform
+
+_T = t.TypeVar("_T")
+
+
+@dataclass_transform(frozen_default=True)
+def frozen_dataclass(cls: type[_T]) -> type[_T]:
+    """Create a dataclass that's effectively immutable but inherits from non-frozen.
+
+    This decorator:
+      1) Applies dataclasses.dataclass(frozen=False) to preserve normal dataclass
+         generation
+      2) Overrides __setattr__ and __delattr__ to block changes post-init
+      3) Tells type-checkers that the resulting class should be treated as frozen
+
+    Parameters
+    ----------
+    cls : Type[_T]
+        The class to convert to a frozen-like dataclass
+
+    Returns
+    -------
+    Type[_T]
+        The processed class with immutability enforced at runtime
+    """
+    # A. Convert to a dataclass with frozen=False
+    cls = dataclasses.dataclass(cls)
+
+    # Save the original __init__ to use in our hooks
+    original_init = cls.__init__
+
+    # C. Create a new __init__ that will call the original and then set _frozen flag
+    def __init__(self: t.Any, *args: t.Any, **kwargs: t.Any) -> None:
+        # Call the original __init__
+        original_init(self, *args, **kwargs)
+        # Set the _frozen flag to make object immutable
+        object.__setattr__(self, "_frozen", True)
+
+    # D. Custom attribute assignment method
+    def __setattr__(self: t.Any, name: str, value: t.Any) -> None:
+        # If _frozen is set and we're trying to set a field, block it
+        if getattr(self, "_frozen", False) and not name.startswith("_"):
+            error_msg = f"{cls.__name__} is immutable: cannot modify field '{name}'"
+            raise AttributeError(error_msg)
+
+        # Allow the assignment
+        object.__setattr__(self, name, value)
+
+    # E. Custom attribute deletion method
+    def __delattr__(self: t.Any, name: str) -> None:
+        # If we're frozen, block deletion
+        if getattr(self, "_frozen", False):
+            error_msg = f"{cls.__name__} is immutable: cannot delete field '{name}'"
+            raise AttributeError(error_msg)
+
+        # Allow the deletion
+        object.__delattr__(self, name)
+
+    # F. Inject into the class
+    cls.__init__ = __init__
+    cls.__setattr__ = __setattr__
+    cls.__delattr__ = __delattr__
+
+    return cls

tests/_internal/test_frozen_dataclass.py

@@ -0,0 +1,162 @@
+"""Tests for the custom frozen_dataclass implementation."""
+
+from __future__ import annotations
+
+import dataclasses
+from datetime import datetime
+
+import pytest
+
+from libtmux._internal.frozen_dataclass import frozen_dataclass
+
+
+# 1. Create a base class that is a normal (mutable) dataclass
+@dataclasses.dataclass
+class BasePane:
+    """Test base class to simulate tmux Pane."""
+
+    pane_id: str
+    width: int
+    height: int
+
+    def resize(self, width: int, height: int) -> None:
+        """Resize the pane (mutable operation)."""
+        self.width = width
+        self.height = height
+
+
+# 2. Subclass the mutable BasePane, but freeze it with our custom decorator
+@frozen_dataclass
+class PaneSnapshot(BasePane):
+    """Test snapshot class with additional fields."""
+
+    # Add snapshot-specific fields
+    captured_content: list[str] = dataclasses.field(default_factory=list)
+    created_at: datetime = dataclasses.field(default_factory=datetime.now)
+    parent_window: WindowSnapshot | None = None
+
+    def resize(self, width: int, height: int) -> None:
+        """Override to prevent resizing."""
+        error_msg = "Snapshot is immutable. resize() not allowed."
+        raise NotImplementedError(error_msg)
+
+
+# Another test class for nested reference handling
+@frozen_dataclass
+class WindowSnapshot:
+    """Test window snapshot class."""
+
+    window_id: str
+    name: str
+    panes: list[PaneSnapshot] = dataclasses.field(default_factory=list)
+
+
+def test_basic_functionality() -> None:
+    """Test that the base class is mutable but the snapshot is not."""
+    # Create a regular mutable pane
+    pane = BasePane(pane_id="pane123", width=80, height=24)
+
+    # Should be mutable
+    pane.width = 100
+    assert pane.width == 100
+    pane.resize(120, 30)
+    assert pane.width == 120
+    assert pane.height == 30
+
+    # Create a frozen snapshot with our decorator
+    snapshot = PaneSnapshot(
+        pane_id=pane.pane_id,
+        width=pane.width,
+        height=pane.height,
+        captured_content=["Line1", "Line2"],
+    )
+
+    # Test type checking
+    assert isinstance(snapshot, PaneSnapshot)
+
+    # Should maintain the inheritance relationship
+    assert isinstance(snapshot, BasePane)
+
+    # Values should be correctly assigned
+    assert snapshot.pane_id == pane.pane_id
+    assert snapshot.width == pane.width
+    assert snapshot.height == pane.height
+    assert snapshot.captured_content == ["Line1", "Line2"]
+    assert isinstance(snapshot.created_at, datetime)
+
+
+def test_immutability() -> None:
+    """Test that the snapshot is immutable."""
+    snapshot = PaneSnapshot(
+        pane_id="pane123", width=80, height=24, captured_content=["Line1"]
+    )
+
+    # Attempting to modify a field should raise AttributeError
+    with pytest.raises(AttributeError) as excinfo:
+        snapshot.width = 200
+    assert "immutable" in str(excinfo.value)
+
+    # Attempting to add a new field should raise AttributeError
+    with pytest.raises(AttributeError) as excinfo:
+        snapshot.new_field = "value"  # type: ignore
+    assert "immutable" in str(excinfo.value)
+
+    # Attempting to delete a field should raise AttributeError
+    with pytest.raises(AttributeError) as excinfo:
+        del snapshot.width
+    assert "immutable" in str(excinfo.value)
+
+    # Calling a method that tries to modify state should fail
+    with pytest.raises(NotImplementedError) as excinfo:
+        snapshot.resize(200, 50)
+    assert "immutable" in str(excinfo.value)
+
+
+def test_nested_references() -> None:
+    """Test that nested structures work properly."""
+    # Create temporary panes (will be re-created with the window)
+    temp_panes: list[PaneSnapshot] = []
+
+    # We need to create objects in a specific order to handle bi-directional references
+    # First, create a window with an empty panes list
+    window = WindowSnapshot(window_id="win1", name="Test Window", panes=temp_panes)
+
+    # Now create panes with references to the window
+    pane1 = PaneSnapshot(pane_id="pane1", width=80, height=24, parent_window=window)
+    pane2 = PaneSnapshot(pane_id="pane2", width=80, height=24, parent_window=window)
+
+    # Update the panes list before it gets frozen
+    # This is a bit of a hack, but that's how you'd need to handle bi-directional
+    # references with immutable objects in real code
+    temp_panes.append(pane1)
+    temp_panes.append(pane2)
+
+    # Test relationships
+    assert pane1.parent_window is window
+    assert pane2.parent_window is window
+    assert pane1 in window.panes
+    assert pane2 in window.panes
+
+    # Can't test by trying to reassign since we'll hit a type error first
+    # But we can still modify the contents of lists (limitation of Python)
+    # Let's verify this limitation exists:
+    pane3 = PaneSnapshot(pane_id="pane3", width=100, height=30)
+    window.panes.append(pane3)
+    assert len(window.panes) == 3  # Successfully modified
+
+    # This is a "leaky abstraction" in Python's immutability model
+    # In real code, consider using immutable collections (tuple, frozenset)
+    # or deep freezing containers
+
+
+def test_internal_attributes() -> None:
+    """Test that internal attributes (starting with _) can be modified."""
+    snapshot = PaneSnapshot(
+        pane_id="pane123",
+        width=80,
+        height=24,
+    )
+
+    # Should be able to set internal attributes
+    snapshot._internal_cache = {"test": "value"}  # type: ignore
+    assert snapshot._internal_cache == {"test": "value"}  # type: ignore