frozen_dataclass(test): Enhance test coverage and add doctests

why: Improve test coverage and documentation for frozen_dataclass

what: - Add comprehensive doctests demonstrating basic usage and limitations - Add test for nested mutability leak scenario - Add test for inheritance compatibility - Improve exception message matching in existing tests

All tests pass successfully (6 pytest tests, 16 doctests)

Author: tony

src/libtmux/_internal/frozen_dataclass.py

@@ -35,6 +35,57 @@ def frozen_dataclass(cls: type[_T]) -> type[_T]:
     -------
     Type[_T]
         The processed class with immutability enforced at runtime
+        
+    Examples
+    --------
+    Basic usage:
+
+    >>> @frozen_dataclass
+    ... class User:
+    ...     id: int
+    ...     name: str
+    >>> user = User(id=1, name="Alice")
+    >>> user.name
+    'Alice'
+    >>> try:
+    ...     user.name = "Bob"
+    ... except AttributeError as e:
+    ...     print(f"Error: {e}")
+    Error: User is immutable: cannot modify field 'name'
+
+    Mutating internal attributes (_-prefixed):
+
+    >>> user._cache = {"logged_in": True}
+    >>> user._cache
+    {'logged_in': True}
+
+    Nested mutable fields limitation:
+
+    >>> @frozen_dataclass
+    ... class Container:
+    ...     items: list[int]
+    >>> c = Container(items=[1, 2])
+    >>> c.items.append(3)  # allowed; mutable field itself isn't protected
+    >>> c.items
+    [1, 2, 3]
+
+    Inheritance from mutable base classes:
+
+    >>> import dataclasses
+    >>> @dataclasses.dataclass
+    ... class MutableBase:
+    ...     value: int
+    >>> @frozen_dataclass
+    ... class ImmutableSub(MutableBase):
+    ...     pass
+    >>> obj = ImmutableSub(42)
+    >>> obj.value
+    42
+    >>> try:
+    ...     obj.value = 100
+    ... except AttributeError as e:
+    ...     print(f"Error: {e}")
+    Error: ImmutableSub is immutable: cannot modify field 'value'
     """
     # A. Convert to a dataclass with frozen=False
     cls = dataclasses.dataclass(cls)

tests/_internal/test_frozen_dataclass.py

@@ -55,38 +55,24 @@ class WindowSnapshot:
     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"],
+# Core behavior tests
+# ------------------
+
+def test_snapshot_initialization() -> None:
+    """Test proper initialization of fields in a frozen dataclass."""
+    pane = PaneSnapshot(
+        pane_id="pane123", 
+        width=80, 
+        height=24, 
+        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)
+    assert pane.pane_id == "pane123"
+    assert pane.width == 80
+    assert pane.height == 24
+    assert pane.captured_content == ["Line1", "Line2"]
+    assert isinstance(pane.created_at, datetime)
 
 
 def test_immutability() -> None:
@@ -96,33 +82,82 @@ def test_immutability() -> None:
     )
 
     # Attempting to modify a field should raise AttributeError
-    with pytest.raises(AttributeError) as excinfo:
+    with pytest.raises(AttributeError, match="immutable.*cannot modify field 'width'"):
         snapshot.width = 200  # type: ignore
-    assert "immutable" in str(excinfo.value)
 
     # Attempting to add a new field should raise AttributeError
-    with pytest.raises(AttributeError) as excinfo:
+    with pytest.raises(AttributeError, match="immutable.*cannot modify field 'new_field'"):
         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:
+    with pytest.raises(AttributeError, match="immutable.*cannot delete field 'width'"):
         del snapshot.width
-    assert "immutable" in str(excinfo.value)
 
     # Calling a method that tries to modify state should fail
-    # Use separate variable for the NotImplementedError exception info
-    with pytest.raises(NotImplementedError) as resize_excinfo:
+    with pytest.raises(NotImplementedError, match="immutable"):
         snapshot.resize(200, 50)
-    assert "immutable" in str(resize_excinfo.value)
 
 
-def test_nested_references() -> None:
-    """Test that nested structures work properly."""
+def test_inheritance() -> None:
+    """Test that frozen classes correctly inherit from mutable base classes."""
+    # Create instances of both classes
+    base_pane = BasePane(pane_id="base1", width=80, height=24)
+    snapshot = PaneSnapshot(pane_id="snap1", width=80, height=24)
+    
+    # Verify inheritance relationship
+    assert isinstance(snapshot, BasePane)
+    assert isinstance(snapshot, PaneSnapshot)
+    
+    # Base class remains mutable
+    base_pane.width = 100
+    assert base_pane.width == 100
+    
+    # Derived class is immutable
+    with pytest.raises(AttributeError, match="immutable"):
+        snapshot.width = 100
+
+
+# Edge case tests
+# --------------
+
+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
+
+
+def test_nested_mutability_leak() -> None:
+    """Test the known limitation that nested mutable fields can still be modified."""
+    # Create a frozen dataclass with a mutable field
+    snapshot = PaneSnapshot(
+        pane_id="pane123",
+        width=80, 
+        height=24,
+        captured_content=["initial"]
+    )
+    
+    # Can't reassign the field itself
+    with pytest.raises(AttributeError, match="immutable"):
+        snapshot.captured_content = ["new"]  # type: ignore
+    
+    # But we can modify its contents (limitation of Python immutability)
+    snapshot.captured_content.append("mutated")
+    assert "mutated" in snapshot.captured_content
+    assert snapshot.captured_content == ["initial", "mutated"]
+
+
+def test_bidirectional_references() -> None:
+    """Test that nested structures with bidirectional references 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)
 
@@ -131,8 +166,6 @@ def test_nested_references() -> None:
     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)
 
@@ -142,26 +175,11 @@ def test_nested_references() -> None:
     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:
+    # Can still modify the contents of mutable collections
     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