Attributes Doc

0.4.0 · active · verified Sun Apr 12

attributes-doc is a Python library providing a hacky implementation of PEP 224 for attribute docstrings. It offers decorators (`attributes_doc`, `enum_doc`) to attach docstrings to class attributes and enum values, and functions (`get_attributes_doc`, `get_doc`) to retrieve them at runtime. The current version is 0.4.0, with a release cadence that has seen updates for Python version compatibility and new features like `enum_doc` in recent major versions.

Warnings

breaking Version 0.4.0 dropped support for Python versions older than 3.8. Users on EOL Python versions will need to upgrade their Python interpreter or pin to an older version of `attributes-doc` (e.g., 0.3.0).
Fix: Upgrade to Python 3.8+ or use `attributes-doc<0.4.0`.
gotcha Python class attributes do not natively support `__doc__` attributes directly like functions or classes do. `attributes-doc` uses a convention where it stores the docstring in `__doc_ATTRNAME__` (for regular class attributes) or directly on the `__doc__` of individual enum *values* (for `enum_doc`). Do not expect `MyClass.attribute.__doc__` to work directly; instead, use `MyClass.__doc_attribute__` or `get_doc(MyClass, 'attribute')`.
Fix: Access attribute docstrings using `MyClass.__doc_attribute__`, `MyEnum.VALUE.__doc__`, or `get_doc(Class, 'attribute_name')`.
gotcha The library name 'attributes-doc' is broad. This library specifically implements a 'hacky implementation of PEP 224' for Python *attribute docstrings*. It is not a general-purpose attribute validation, mutation, or metaclass utility (like 'characteristic' or 'traits'), nor is it related to Git attributes or HTML attributes.
Fix: Understand that the library's scope is focused solely on adding and retrieving docstrings for class attributes and enum members.

Install

pip install attributes-doc Install latest version

Imports

attributes_doc

from attributes_doc import attributes_doc

get_attributes_doc

from attributes_doc import get_attributes_doc

enum_doc
```
from attributes_doc import enum_doc
```
get_doc
```
from attributes_doc import get_doc
```

Quickstart

This example demonstrates how to use the `attributes_doc` decorator for regular classes and `enum_doc` for Enum classes. It also shows how to retrieve the attribute docstrings using both the generated `__doc_ATTRNAME__` attribute (for classes) or `__doc__` (for enum values) and the `get_doc` helper function.

from attributes_doc import attributes_doc, enum_doc, get_doc
from enum import Enum

@attributes_doc
class MyClass:
    foo = 1
    """This is the docstring for foo."""

    bar = 'hello'
    """Docstring for bar."""

print(MyClass.__doc_foo__) # Access docstring via a special attribute
print(get_doc(MyClass, 'bar')) # Use get_doc helper

@enum_doc
class MyEnum(Enum):
    VALUE_A = 1
    """Description for value A."""

    VALUE_B = 2
    """Description for value B."""

print(MyEnum.VALUE_A.__doc__) # Access docstring directly on enum value
print(get_doc(MyEnum, 'VALUE_B')) # Use get_doc helper

view raw JSON →