attr-docs 0.3.0

Runtime access to Python class attribute, enum member, and dataclass field docstrings

attr-docs

Runtime access to Python class attribute, enum member, and dataclass field docstrings

Installation

pip install attr-docs

Usage

Class

attr_docs 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

Enums support lazy parsing of member docstrings, the decorator will not add overhead until you access the docstring of a member for the first time.

from enum import Enum
attr_docs 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 these standard class access patterns
docs = get_docstrings(Status)
print(docs["COMPLETED"])   # "Task has finished successfully."

# 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

from dataclasses import dataclass, fields
attr_docs 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__']}")