frozen_dataclass(docs/test): Enhance documentation and test precision

why: Improve clarity, security awareness, and test robustness

what: - Simplify doctests with conventional exception handling patterns - Add explicit example of using immutable collections for deep immutability - Enhance security warnings about _frozen flag bypass vulnerability - Use precise regex patterns in test assertions for better error detection - Improve documentation of design choices and implementation limitations

security: Explicitly document the _frozen attribute vulnerability with clear examples and suggested mitigations

Author: tony

src/libtmux/_internal/frozen_dataclass.py

@@ -47,11 +47,10 @@ def frozen_dataclass(cls: type[_T]) -> type[_T]:
     >>> 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'
+    >>> user.name = "Bob"
+    Traceback (most recent call last):
+        ...
+    AttributeError: User is immutable: cannot modify field 'name'
 
     Mutating internal attributes (_-prefixed):
 
@@ -68,6 +67,13 @@ def frozen_dataclass(cls: type[_T]) -> type[_T]:
     >>> c.items.append(3)  # allowed; mutable field itself isn't protected
     >>> c.items
     [1, 2, 3]
+    >>> # For deep immutability, use immutable collections (tuple, frozenset)
+    >>> @frozen_dataclass
+    ... class ImmutableContainer:
+    ...     items: tuple[int, ...] = (1, 2)
+    >>> ic = ImmutableContainer()
+    >>> ic.items
+    (1, 2)
 
     Inheritance from mutable base classes:
 
@@ -81,26 +87,25 @@ def frozen_dataclass(cls: type[_T]) -> type[_T]:
     >>> 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'
+    >>> obj.value = 100
+    Traceback (most recent call last):
+        ...
+    AttributeError: ImmutableSub is immutable: cannot modify field 'value'
 
     Security consideration - modifying the _frozen flag:
 
     >>> @frozen_dataclass
     ... class SecureData:
     ...     secret: str
     >>> data = SecureData(secret="password123")
-    >>> try:
-    ...     data.secret = "hacked"
-    ... except AttributeError as e:
-    ...     print(f"Protected: {e}")
-    Protected: SecureData is immutable: cannot modify field 'secret'
-    >>> # However, the _frozen flag can be modified to bypass protection:
-    >>> data._frozen = False
     >>> data.secret = "hacked"
+    Traceback (most recent call last):
+        ...
+    AttributeError: SecureData is immutable: cannot modify field 'secret'
+    >>> # CAUTION: The _frozen attribute can be modified to bypass immutability protection
+    >>> # This is a known limitation of this implementation
+    >>> data._frozen = False  # intentionally bypassing immutability
+    >>> data.secret = "hacked"  # now works because object is no longer frozen
     >>> data.secret
     'hacked'
     """

tests/_internal/test_frozen_dataclass.py

@@ -80,22 +80,20 @@ def test_immutability() -> None:
         pane_id="pane123", width=80, height=24, captured_content=["Line1"]
     )
 
-    # Attempting to modify a field should raise AttributeError
-    with pytest.raises(AttributeError, match="immutable.*cannot modify field 'width'"):
+    # Attempting to modify a field should raise AttributeError with precise error message
+    with pytest.raises(AttributeError, match=r"PaneSnapshot is immutable: cannot modify field 'width'"):
         snapshot.width = 200  # type: ignore
 
-    # Attempting to add a new field should raise AttributeError
-    with pytest.raises(
-        AttributeError, match="immutable.*cannot modify field 'new_field'"
-    ):
+    # Attempting to add a new field should raise AttributeError with precise error message
+    with pytest.raises(AttributeError, match=r"PaneSnapshot is immutable: cannot modify field 'new_field'"):
         snapshot.new_field = "value"  # type: ignore
 
-    # Attempting to delete a field should raise AttributeError
-    with pytest.raises(AttributeError, match="immutable.*cannot delete field 'width'"):
+    # Attempting to delete a field should raise AttributeError with precise error message
+    with pytest.raises(AttributeError, match=r"PaneSnapshot is immutable: cannot delete field 'width'"):
         del snapshot.width
 
     # Calling a method that tries to modify state should fail
-    with pytest.raises(NotImplementedError, match="immutable"):
+    with pytest.raises(NotImplementedError, match=r"Snapshot is immutable. resize\(\) not allowed."):
         snapshot.resize(200, 50)
 
 
@@ -189,7 +187,12 @@ def test_bidirectional_references() -> None:
 
 
 class DimensionTestCase(t.NamedTuple):
-    """Test fixture for validating dimensions in PaneSnapshot."""
+    """Test fixture for validating dimensions in PaneSnapshot.
+    
+    Note: This implementation intentionally allows any dimension values, including
+    negative or extremely large values. In a real-world application, you might want
+    to add validation to the class constructor if certain dimension ranges are required.
+    """
 
     test_id: str
     width: int
@@ -284,11 +287,12 @@ def test_frozen_flag(
     error_match: str | None,
 ) -> None:
     """Test behavior when attempting to manipulate the _frozen flag.
-
+    
     Note: We discovered that setting _frozen=False actually allows mutation,
     which could be a potential security issue if users know about this behavior.
     In a more secure implementation, the _frozen attribute might need additional
-    protection to prevent this bypass mechanism.
+    protection to prevent this bypass mechanism, such as making it a property with
+    a setter that raises an exception.
     """
     # Create a frozen dataclass
     pane = PaneSnapshot(pane_id="test_frozen", width=80, height=24)