Metadata-Version: 2.4
Name: attr-docs
Version: 1.0.0
Summary: Runtime access to Python class attribute, enum member, and dataclass field docstrings
Keywords: docstrings,PEP 224,pep224,class attributes,attribute docstrings,error reporting,enum,enum members,member docstrings,dataclasses,dataclass fields,field docstrings,ast,sphinx,autodoc
Author: gesslerpd
Author-email: gesslerpd <gesslerpd@users.noreply.github.com>
License-Expression: MIT
Requires-Python: >=3.10
Project-URL: Homepage, https://github.com/gesslerpd/attr-docs
Project-URL: Repository, https://github.com/gesslerpd/attr-docs
Project-URL: Issues, https://github.com/gesslerpd/attr-docs/issues
Description-Content-Type: text/markdown


# attr-docs

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

## Installation

```bash
pip install attr-docs
```

## Usage

### Class

```python
from 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 get/set the docstring of a member.

```python
from enum import Enum
from 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

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

    # Python 3.14+ supports field.doc
    if hasattr(field, "doc"):
        print(f"{field.name}: {field.doc}")

```
