fix(frozen_dataclass): improve type hints and simplify doctests in implementation file

Author: tony

src/libtmux/_internal/frozen_dataclass_sealable.py

@@ -27,79 +27,6 @@
 - Private attributes
 - Deep copying on sealing
 - Slots
-
-Example:
-    ```python
-    from dataclasses import dataclass, field
-    from typing import Optional, List
-    from libtmux._internal.frozen_dataclass_sealable import (
-        frozen_dataclass_sealable,
-        mutable_during_init,
-    )
-
-    # Mutable base class
-    @dataclass
-    class BasePane:
-        pane_id: str
-        width: int
-        height: int
-
-        def resize(self, width: int, height: int) -> None:
-            self.width = width
-            self.height = height
-
-    # Frozen subclass with field-level mutability
-    @frozen_dataclass_sealable
-    class PaneSnapshot(BasePane):
-        # Regular immutable fields
-        captured_content: List[str] = field(default_factory=list)
-
-        # This field can be modified during initialization
-        parent_window: Optional['WindowSnapshot'] = field(
-            default=None,
-            metadata={"mutable_during_init": True}
-        )
-
-        # Override method to block mutation
-        def resize(self, width: int, height: int) -> None:
-            raise NotImplementedError("Snapshot is immutable. resize() not allowed.")
-
-    # Frozen class with circular reference
-    @frozen_dataclass_sealable
-    class WindowSnapshot:
-        window_id: str
-        name: str
-
-        # This field can be modified during initialization
-        panes: List[PaneSnapshot] = field(
-            default_factory=list,
-            metadata={"mutable_during_init": True}
-        )
-
-    # Create objects with circular references
-    window = WindowSnapshot(window_id="win1", name="Main")  # Not sealed yet
-    pane1 = PaneSnapshot(pane_id="1", width=80, height=24)  # Not sealed yet
-    pane2 = PaneSnapshot(pane_id="2", width=80, height=24)  # Not sealed yet
-
-    # Establish circular references
-    window.panes.append(pane1)
-    window.panes.append(pane2)
-    pane1.parent_window = window
-    pane2.parent_window = window
-
-    # Seal all objects
-    window.seal()
-    pane1.seal()
-    pane2.seal()
-
-    # Now all objects are fully immutable
-    ```
-
-Implementation Notes:
-    - Uses a custom `__setattr__` to enforce immutability rules
-    - Internal attributes (starting with '_') can still be modified
-    - Known limitation: the contents of mutable objects (lists, dicts) can still
-      be modified even after sealing
 """
 
 from __future__ import annotations
@@ -199,23 +126,49 @@ def is_sealable(cls_or_obj: t.Any) -> bool:
     """Check if a class or object is sealable.
 
     Args:
-        cls_or_obj: A class or object to check
+        cls_or_obj: The class or object to check
 
-    Returns:
+    Returns
+    -------
         True if the class or object is sealable, False otherwise
+    
+    Examples:
+        >>> from dataclasses import dataclass
+        >>> from libtmux._internal.frozen_dataclass_sealable import (
+        ...     frozen_dataclass_sealable, is_sealable
+        ... )
+        
+        >>> # Regular class is not sealable
+        >>> @dataclass
+        ... class Regular:
+        ...     value: int
+        
+        >>> is_sealable(Regular)
+        False
+        >>> regular = Regular(value=42)
+        >>> is_sealable(regular)
+        False
+        
+        >>> # Non-class objects are not sealable
+        >>> is_sealable("string")
+        False
+        >>> is_sealable(42)
+        False
+        >>> is_sealable(None)
+        False
     """
-    # Check if it's a class
+    # If it's a class, check if it has a seal method
     if isinstance(cls_or_obj, type):
-        return hasattr(cls_or_obj, "seal") and callable(cls_or_obj.seal)
+        return hasattr(cls_or_obj, "seal") and callable(getattr(cls_or_obj, "seal"))
 
-    # It's an object instance
-    return hasattr(cls_or_obj, "seal") and callable(cls_or_obj.seal)
+    # If it's an instance, check if it has a seal method
+    return hasattr(cls_or_obj, "seal") and callable(getattr(cls_or_obj, "seal"))
 
 
 @dataclass_transform(frozen_default=True)
 def frozen_dataclass_sealable(
     cls: type | None = None, /, **kwargs: t.Any
-) -> t.Any:  # mypy doesn't handle complex return types well here
+) -> t.Callable[[type], type] | type:
     """Create a dataclass that is immutable, with field-level mutability control.
 
     Enhances the standard dataclass with: