Skip to content

missing-public-class-attribute-documentation (PDF508)

Added in 1.0.0 Never fix Convention

Part of the PDF rule category.

View source · View documentation source · Search issues

Fix is not available.

Rule is disabled if docstring-convention is none or pep257.

What it does

Checks that public class attributes are documented either in the class docstring attribute documentation or by an adjacent attribute docstring.

The rule compares supported class attribute assignments against names documented in Google Attributes sections, NumPy Attributes sections, reStructuredText :ivar:, :cvar:, :var:, and :vartype: fields, and adjacent attribute docstrings. Class-scope assignments, annotated assignments, multi-target assignments, and tuple-unpacked assignment leaves are inventoried. Private attributes are never required.

By default, class-scope attributes are required and self.* assignments from __init__ are accepted as existing attributes but are not required. Enable docstring-require-init-attribute-documentation to require supported self.* assignments too. Assignments inside methods other than __init__, list destructuring targets, unsupported tuple leaves, subscript targets, cls.*, and arbitrary object attributes are not class attribute inventory entries for this rule.

PDF508 checks whether public class attributes have any recognized documentation. It does not care whether that documentation is in the class docstring or attached to the assignment; use PDF518 or PDF519 for a location policy, PDF509 for stale class docstring entries, and PDF512 for duplicated class attribute documentation.

Why is this useful?

Class attribute documentation can otherwise drift from the actual class surface.

Ruff compatibility

None.

Examples

Missing public class attribute documentation is reported when a class has attribute documentation but omits a public class attribute:

docstring-convention = "google"

class Client:
    """HTTP client.

    Attributes:
        timeout (float): Request timeout.
    """

    timeout: float
    retries: int

PDF508: Line 9: Public class attribute 'retries' is missing docstring documentation

An empty recognized Attributes section still opts the class into missing attribute checks:

docstring-convention = "google"

class Client:
    """HTTP client.

    Attributes:
    """

    timeout: float

PDF508: Line 7: Public class attribute 'timeout' is missing docstring documentation

Adjacent attribute docstrings document their assignments, including every simple target in a multi-target assignment and supported tuple-unpacked assignment. Private attributes are not required:

docstring-convention = "google"

class Client:
    timeout: float
    """Request timeout."""

    primary = fallback = "https://example.com"
    """Request endpoints."""

    host, (port, *aliases) = endpoint_parts
    """Unpacked endpoint parts."""

    _token: str

NumPy comma-separated attribute entries document each listed name independently:

docstring-convention = "numpy"

class Client:
    """HTTP client.

    Attributes
    ----------
    primary, fallback : str
        Request endpoints.
    """

    primary = fallback = "https://example.com"
    retries: int

PDF508: Line 11: Public class attribute 'retries' is missing docstring documentation

reStructuredText attribute fields are parsed under the rest convention:

docstring-convention = "rest"

class Client:
    """HTTP client.

    :ivar timeout: Request timeout.
    """

    timeout: float
    retries: int

PDF508: Line 8: Public class attribute 'retries' is missing docstring documentation

self.* assignments in __init__ are required only when docstring-require-init-attribute-documentation is enabled:

docstring-convention = "google"
docstring-require-init-attribute-documentation = true

class Client:
    """HTTP client.

    Attributes:
        timeout (float): Request timeout.
    """

    timeout: float

    def __init__(self):
        self.retries = 3

PDF508: Line 11: Public class attribute 'retries' is missing docstring documentation

Options