fix typehint

Author: gesslerpd

.github/workflows/ci.yml

@@ -13,7 +13,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
 
     steps:
     - uses: actions/checkout@v4

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "runtime-docstrings"
-version = "0.1.2"
+version = "0.1.3"
 description = "Runtime access to Python class attribute docstrings (PEP 224)"
 readme = "README.md"
 license = "MIT"
@@ -40,3 +40,18 @@ branch = true
 
 [tool.coverage.report]
 precision = 2
+
+[tool.coverage.html]
+show_contexts = true
+
+[tool.ruff]
+fix = true
+
+line-length = 100
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = ["COM812", "S101"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"

src/runtime_docstrings/__init__.py

@@ -1 +1,4 @@
-from ._parser import docstrings as docstrings, get_docstrings as get_docstrings
+"""Runtime attribute docstrings."""
+
+from ._parser import docstrings as docstrings
+from ._parser import get_docstrings as get_docstrings

src/runtime_docstrings/_parser.py

@@ -1,14 +1,15 @@
 from __future__ import annotations
 
-
+import ast
 import dataclasses
 import inspect
-
-import warnings
-from textwrap import dedent
-import ast
 import types
+import warnings
 from enum import Enum
+from textwrap import dedent
+from typing import TypeVar
+
+T = TypeVar("T", bound=type)
 
 
 def _parse_docstrings(node: ast.ClassDef) -> dict[str, str]:
@@ -28,9 +29,7 @@ def _parse_docstrings(node: ast.ClassDef) -> dict[str, str]:
                 continue
 
         match body[index]:
-            case ast.Expr(value=ast.Constant(value=doc_str)) if isinstance(
-                doc_str, str
-            ):
+            case ast.Expr(value=ast.Constant(value=doc_str)) if isinstance(doc_str, str):
                 docs[name] = inspect.cleandoc(doc_str)
                 index += 1
     return docs
@@ -45,6 +44,7 @@ def get_docstrings(cls: type) -> dict[str, str]:
     Returns:
         A dictionary where keys are attribute names and values are their
         corresponding docstrings.
+
     """
     if "__attribute_docs__" in cls.__dict__:
         return cls.__attribute_docs__
@@ -81,23 +81,27 @@ def _attach_enum(cls: type[Enum], comments: dict[str, str]) -> None:
         canonical_name = member.name
         if name != canonical_name and name in comments:
             warnings.warn(
-                f"Enum alias member {cls.__name__}.{name} has docstring that should be documented on {cls.__name__}.{canonical_name}"
+                f"Enum alias member {cls.__name__}.{name} has docstring "
+                f"that should be documented on {cls.__name__}.{canonical_name}",
+                stacklevel=1,
             )
             if canonical_name not in comments:
                 member.__doc__ = comments[name]
 
 
-def docstrings(cls: type) -> type:
-    """Decorator that attaches attribute/member docstrings to a class.
+def docstrings(cls: T) -> T:
+    """Attach attribute/member docstrings to a class.
 
-    If the class is an enum, docstrings are attached via enum members.
+    If the class is an enum, attach docstrings via enum members.
 
-    If the class is a dataclass, docstrings are attached via field metadata.
+    If the class is a dataclass, attach docstrings via field metadata.
 
-    Parameters:
+    Args:
         cls: The class to process.
+
     Returns:
         The same class with attached docstrings.
+
     """
     assert inspect.isclass(cls), "cls must be a class"
 

tests/test_class.py

@@ -2,7 +2,11 @@
 
 
 def _prop(self):
-    """A property."""
+    """Property.
+
+    Returns: The property value.
+
+    """
     return self.__doc__  # pragma: no cover
 
 
@@ -77,7 +81,7 @@ def test_all():
 
     assert Child.__doc_BASE_VAR__ == "Represents a base variable."
     assert Child.__doc_CHILD_VAR__ == "Represents a child variable."
-    assert Child.ins_prop.__doc__ == "A property."
+    assert Child.ins_prop.__doc__.startswith("Property.")
     assert Child.another_prop.__doc__ == "Another property."
 
     assert Child.__doc__ is None

tests/test_dataclass.py

@@ -1,10 +1,9 @@
 """Test dataclass support for runtime_docs."""
 
 import dataclasses
-from dataclasses import dataclass, field, InitVar
-from typing import List, Dict, Optional, ClassVar
+from dataclasses import InitVar, dataclass, field
 from enum import Enum
-
+from typing import ClassVar
 
 from runtime_docstrings import docstrings, get_docstrings
 
@@ -20,12 +19,12 @@ class BasicDataClass:
     age: int = 30
     """The age field with default value."""
 
-    tags: List[str] = dataclasses.field(default_factory=list)
+    tags: list[str] = dataclasses.field(default_factory=list)
     """List of tags associated with this entity."""
 
     active: bool = True
 
-    description: Optional[str] = None
+    description: str | None = None
     """Optional description text."""
 
 
@@ -87,31 +86,27 @@ class SlottedDataClass:
     age: int = 30
     """The age field with default value."""
 
-    tags: List[str] = field(default_factory=list)
+    tags: list[str] = field(default_factory=list)
     """List of tags associated with this entity."""
 
     active: bool = True
 
-    description: Optional[str] = None
+    description: str | None = None
     """Optional description text."""
 
 
 def test_slotted_dataclass_docstrings():
     """Test that docstrings are correctly extracted from slotted dataclass fields."""
     docs = get_docstrings(SlottedDataClass)
 
-    assert "name" in docs
     assert docs["name"] == "The name field."
 
-    assert "age" in docs
     assert docs["age"] == "The age field with default value."
 
-    assert "tags" in docs
     assert docs["tags"] == "List of tags associated with this entity."
 
     assert "active" not in docs  # No docstring for this field
 
-    assert "description" in docs
     assert docs["description"] == "Optional description text."
 
 
@@ -148,36 +143,31 @@ class DataClassWithMetadata:
     """The name field with metadata."""
 
     age: int = field(
-        default=30, metadata={"validator": "int_validator", "min": 0, "max": 120}
+        default=30,
+        metadata={"validator": "int_validator", "min": 0, "max": 120},
     )
     """The age field with default value and metadata."""
 
-    tags: List[str] = field(
-        default_factory=list, metadata={"doc": "Existing doc in metadata"}
+    tags: list[str] = field(
+        default_factory=list,
+        metadata={"doc": "Existing doc in metadata"},
     )
     """List of tags with existing doc in metadata."""
 
 
 def test_field_metadata_docstrings():
     """Test that docstrings are correctly added to field metadata."""
-
     fields = {f.name: f for f in dataclasses.fields(DataClassWithMetadata)}
 
     # Check that the field docstrings are correctly stored
     assert "name" in fields
     assert fields["name"].metadata["__doc__"] == "The name field with metadata."
 
     assert "age" in fields
-    assert (
-        fields["age"].metadata["__doc__"]
-        == "The age field with default value and metadata."
-    )
+    assert fields["age"].metadata["__doc__"] == "The age field with default value and metadata."
 
     assert "tags" in fields
-    assert (
-        fields["tags"].metadata["__doc__"]
-        == "List of tags with existing doc in metadata."
-    )
+    assert fields["tags"].metadata["__doc__"] == "List of tags with existing doc in metadata."
 
 
 def test_field_metadata_preservation():
@@ -248,9 +238,7 @@ def test_dataclass_inheritance():
     assert "shared_field" in grandparent_docs
     assert grandparent_docs["shared_field"] == "Shared field from grandparent."
     assert "another_shared" in grandparent_docs
-    assert (
-        grandparent_docs["another_shared"] == "Another shared field from grandparent."
-    )
+    assert grandparent_docs["another_shared"] == "Another shared field from grandparent."
 
     parent_docs = get_docstrings(ParentDataClass)
     assert "parent_field" in parent_docs
@@ -282,10 +270,7 @@ def test_dataclass_inheritance():
     assert ParentDataClass.__doc_shared_field__ == "Shared field from parent."
 
     assert hasattr(GrandParentDataClass, "__doc_another_shared__")
-    assert (
-        GrandParentDataClass.__doc_another_shared__
-        == "Another shared field from grandparent."
-    )
+    assert GrandParentDataClass.__doc_another_shared__ == "Another shared field from grandparent."
 
     assert hasattr(ChildDataClass, "__doc_another_shared__")
     assert ChildDataClass.__doc_another_shared__ == "Overridden shared field."
@@ -301,10 +286,7 @@ def test_dataclass_inheritance():
     assert ParentDataClass.__doc_parent_field__ == "The parent field."
     assert ParentDataClass.__doc_grandparent_field__ == "The grandparent field."
     assert ParentDataClass.__doc_shared_field__ == "Shared field from parent."
-    assert (
-        ParentDataClass.__doc_another_shared__
-        == "Another shared field from grandparent."
-    )
+    assert ParentDataClass.__doc_another_shared__ == "Another shared field from grandparent."
 
 
 @docstrings
@@ -430,7 +412,6 @@ def test_api_consistency():
 
 def test_complex_inheritance_mro():
     """Test MRO resolution with complex inheritance involving different class types."""
-
     # Test MRO resolution for complex inheritance
     assert ComplexInheritance.__doc_complex_field__ == "Complex field."
 
@@ -526,10 +507,7 @@ def test_multi_level_mixed_inheritance():
     # Test MRO resolution for intermediate class
     assert IntermediateDataClass.__doc_base_attr__ == "Base attribute."
     assert IntermediateDataClass.__doc_intermediate_field__ == "Intermediate field."
-    assert (
-        IntermediateDataClass.__doc_shared_attr__
-        == "Shared attribute from intermediate."
-    )
+    assert IntermediateDataClass.__doc_shared_attr__ == "Shared attribute from intermediate."
 
     # Test instance creation and attribute access
     child_instance = ChildRegularClass()
@@ -625,11 +603,11 @@ def test_special_char_docstrings():
 class DefaultFactoryDataClass:
     """A dataclass with default factory functions."""
 
-    simple_list: List[str] = field(default_factory=list)
+    simple_list: list[str] = field(default_factory=list)
     """A simple list with default factory."""
 
-    complex_dict: Dict[str, List[int]] = field(
-        default_factory=lambda: {"default": [1, 2, 3]}
+    complex_dict: dict[str, list[int]] = field(
+        default_factory=lambda: {"default": [1, 2, 3]},
     )
     """A complex dictionary with default factory lambda."""
 
@@ -740,7 +718,7 @@ class ClassVarDataClass:
     DEFAULT_AGE: ClassVar[int] = 30
     """Default age constant."""
 
-    CONSTANTS: ClassVar[Dict[str, str]] = {"DEFAULT_NAME": "Unknown"}
+    CONSTANTS: ClassVar[dict[str, str]] = {"DEFAULT_NAME": "Unknown"}
     """Dictionary of constants."""