v0.1.0

Author: gesslerpd

.gitignore

@@ -9,5 +9,9 @@ wheels/
 # Virtual environments
 .venv
 
-# Lock files
+# uv
 uv.lock
+
+# coverage
+.coverage
+.coverage.*

README.md

@@ -2,3 +2,106 @@
 # runtime-docstrings
 
 Runtime access to Python class attribute docstrings (PEP 224)
+
+## Installation
+
+```bash
+pip install runtime-docstrings
+```
+
+## Usage
+
+### Class
+
+```python
+from runtime_docstrings import docstrings, get_docstrings
+
+@docstrings
+class Person:
+    """A person with various attributes."""
+    
+    name: str
+    """The person's full name."""
+
+    email: str
+    """Contact email address."""
+
+    age: int = 0
+    """The person's age in years."""
+
+# Access docstrings map directly on class (IDE style)
+docs = get_docstrings(Person)
+print(docs["name"])    # "The person's full name."
+print(docs["age"])     # "The person's age in years."
+print(docs["email"])   # "Contact email address."
+
+# Access via PEP 224 style attributes (uses Python MRO lookup)
+print(Person.__doc_name__)   # "The person's full name."
+print(Person.__doc_age__)    # "The person's age in years."
+print(Person.__doc_email__)  # "Contact email address."
+```
+
+### Enum
+
+```python
+from enum import Enum
+from runtime_docstrings import docstrings
+
+@docstrings
+class Status(Enum):
+    """Status enumeration for task tracking."""
+    
+    PENDING = "pending"
+    """Task is waiting to be processed."""
+    
+    RUNNING = "running"
+    """Task is currently being executed."""
+    
+    COMPLETED = "completed"
+    """Task has finished successfully."""
+    
+    FAILED = "failed"
+    """Task encountered an error."""
+
+# Supports all the standard class access patterns
+
+# Access via enum member __doc__ attribute
+print(Status.PENDING.__doc__)    # "Task is waiting to be processed."
+print(Status.COMPLETED.__doc__)  # "Task has finished successfully."
+
+# Iterate through all members with their documentation
+for member in Status:
+    if member.__doc__:
+        print(f"{member.name}: {member.__doc__}")
+```
+
+### Dataclass
+
+```python
+from dataclasses import dataclass, fields
+from runtime_docstrings import docstrings, get_docstrings
+
+@docstrings
+@dataclass
+class Product:
+    """A product in an e-commerce system."""
+    
+    name: str
+    """Product name."""
+    
+    price: float
+    """Price in USD."""
+
+    category: str = ""
+    """Product category."""
+    
+    description: str = ""
+    """Detailed product description."""
+
+# Supports all the standard class access patterns
+
+# Access via dataclass field metadata
+for field in fields(Product):
+    if field.metadata.get("__doc__"):
+        print(f"{field.name}: {field.metadata['__doc__']}")
+```

pyproject.toml

@@ -1,18 +1,29 @@
 [project]
 name = "runtime-docstrings"
-version = "0.0.0"
+version = "0.1.0"
 description = "Runtime access to Python class attribute docstrings (PEP 224)"
 readme = "README.md"
 authors = [{ name = "gesslerpd", email = "[email protected]" }]
 requires-python = ">=3.10"
 dependencies = []
 
+[project.urls]
+Homepage = "https://github.com/gesslerpd/runtime-docstrings"
+Repository = "https://github.com/gesslerpd/runtime-docstrings"
+Issues = "https://github.com/gesslerpd/runtime-docstrings/issues"
+
 [build-system]
 requires = ["uv-build>=0.8.2"]
 build-backend = "uv_build"
 
 [dependency-groups]
-dev = [
-    "pytest>=8.4.1",
-    "ruff>=0.12.4",
-]
+dev = ["pytest>=8.4.1", "pytest-cov>=6.2.1", "ruff>=0.12.4"]
+
+[tool.pytest.ini_options]
+addopts = "--import-mode=importlib"
+
+[tool.coverage.run]
+branch = true
+
+[tool.coverage.report]
+precision = 2

src/runtime_docstrings/__init__.py

@@ -0,0 +1 @@
+from ._parser import docstrings as docstrings, get_docstrings as get_docstrings

src/runtime_docstrings/_parser.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+
+import dataclasses
+import inspect
+
+import warnings
+from textwrap import dedent
+import ast
+import types
+from enum import Enum
+from typing import TypeVar
+
+T = TypeVar("T", bound=type)
+
+
+def _parse_docstrings(node: ast.ClassDef) -> dict[str, str]:
+    docs: dict[str, str] = {}
+    body = node.body
+    for index in range(len(body) - 1):
+        match body[index]:
+            case ast.AnnAssign(target=ast.Name(id=name)):
+                pass
+            case ast.Assign(targets=[ast.Name(id=name)]):
+                pass
+            case _:
+                continue
+
+        match body[index + 1]:
+            case ast.Expr(value=ast.Constant(value=doc_str)) if isinstance(
+                doc_str, str
+            ):
+                docs[name] = inspect.cleandoc(doc_str)
+    return docs
+
+
+def get_docstrings(cls: type) -> dict[str, str]:
+    if "__attribute_docs__" in cls.__dict__:
+        return cls.__attribute_docs__
+    source = dedent(inspect.getsource(cls))
+    tree = ast.parse(source)
+    node = tree.body[0]
+    assert isinstance(node, ast.ClassDef)
+    # only process top-level class definition (no NodeVisitor recursion)
+    docs = _parse_docstrings(node)
+    # IDE style (no MRO resolution)
+    cls.__attribute_docs__ = docs
+    return docs
+
+
+def _attach_class(cls: type, comments: dict[str, str]) -> None:
+    for name, docstring in comments.items():
+        setattr(cls, f"__doc_{name}__", docstring)
+
+
+def _attach_dataclass(cls: type, comments: dict[str, str]) -> None:
+    for field in dataclasses.fields(cls):
+        field.metadata = types.MappingProxyType(
+            {"__doc__": comments.get(field.name), **field.metadata}
+        )
+
+
+def _attach_enum(cls: type[Enum], comments: dict[str, str]) -> None:
+    # enum members (canonical)
+    for member in cls:
+        member.__doc__ = comments.get(member.name)
+
+    # enum alias members
+    for name, member in cls.__members__.items():
+        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}"
+            )
+            if canonical_name not in comments:
+                member.__doc__ = comments[name]
+
+
+def docstrings(cls: T) -> T:
+    assert inspect.isclass(cls), "cls must be a class"
+
+    # Extract docstrings from the class definition
+    comments = get_docstrings(cls)
+    if not comments:
+        return cls
+
+    _attach_class(cls, comments)
+
+    if issubclass(cls, Enum):
+        _attach_enum(cls, comments)
+    elif dataclasses.is_dataclass(cls):
+        _attach_dataclass(cls, comments)
+
+    return cls

tests/test_class.py

@@ -0,0 +1,84 @@
+from runtime_docstrings import docstrings, get_docstrings
+
+
+def _prop(self):
+    """A property."""
+    return self.__doc__  # pragma: no cover
+
+
+@docstrings
+class Base:
+    """Base class."""
+
+    BASE_VAR = "base"
+    """Represents a base variable."""
+
+    ins_prop = property(_prop)
+    """Instance property."""
+
+    another_prop = property(_prop, doc="Another property.")
+    """Another instance property."""
+
+    """Ok"""
+    OK: str = "ok"
+
+    AL: str
+    """Alright"""
+
+    OKR = ""
+    """okr"""
+
+    @docstrings
+    class Inner:
+        """Inner class for demonstration."""
+
+        INNER_VAR: int = 42
+        """An inner variable."""
+        INNER_VAR2: str = "inner"
+        """Another inner variable."""
+
+
+@docstrings
+class Child(Base):
+    BASE_VAR = "overridden_base"
+
+    CHILD_VAR = "child"
+    """Represents a child variable."""
+
+
+@docstrings
+class NoDocClass:
+    """This class has no attribute docstrings."""
+
+    """Test"""
+    NO_DOC_VAR = "no_doc"
+
+    HEY = 3
+
+
+def test_no_doc_class():
+    assert get_docstrings(NoDocClass) == {}
+
+
+def test_all():
+    assert get_docstrings(Base) == {
+        "AL": "Alright",
+        "OKR": "okr",
+        "BASE_VAR": "Represents a base variable.",
+        "another_prop": "Another instance property.",
+        "ins_prop": "Instance property.",
+    }
+    assert get_docstrings(Base.Inner) == {
+        "INNER_VAR": "An inner variable.",
+        "INNER_VAR2": "Another inner variable.",
+    }
+
+    assert get_docstrings(Child) == {"CHILD_VAR": "Represents a child variable."}
+
+    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.another_prop.__doc__ == "Another property."
+
+    assert Child.__doc__ is None
+    assert Base.__doc__ == "Base class."