Skip to content

module-attribute-missing-description (PDF716)

Added in 1.1.0 Never fix Convention Module and Fragment

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 parsed module attribute entries in owning module docstrings include a prose description.

Only entries that match inventoried module attributes are checked. Attached module attribute docstrings are intentionally not checked by PDF7xx rules.

An orphan reST :vartype name: field has no attribute value entry whose description PDF716 could check, so PDF722 owns that structural problem.

Why is this useful?

Module attribute entries should explain exported state or constants.

Ruff compatibility

None.

Examples

PDF716 reports module attribute entries without descriptions:

docstring-convention = "google"

"""Module.

Attributes:
    timeout (int):
    retries:
"""

timeout: int = 1
retries: int = 3

PDF716: Line 4: Module attribute 'timeout' docstring entry is missing a description
PDF716: Line 5: Module attribute 'retries' docstring entry is missing a description

Module attribute entries with descriptions are accepted:

docstring-convention = "google"

"""Module.

Attributes:
    timeout (int): Timeout in seconds.
"""

timeout: int = 1

NumPy entries that document multiple attributes are checked once per matching module attribute, even though the findings share one entry line:

docstring-convention = "numpy"

"""Module.

Attributes
----------
timeout, retries : int
"""

timeout: int = 1
retries: int = 3

PDF716: Line 5: Module attribute 'timeout' docstring entry is missing a description
PDF716: Line 5: Module attribute 'retries' docstring entry is missing a description

For reST, PDF716 checks attribute value fields rather than standalone type fields. A paired empty value field is reported, while a type-only entry for another real attribute is left to PDF722:

docstring-convention = "rest"

"""Module.

:vartype timeout: int
:var timeout:
:vartype retries: int
"""

timeout: int = 1
retries: int = 3

PDF716: Line 4: Module attribute 'timeout' docstring entry is missing a description

Attached module attribute docstrings are ignored by PDF7xx owning-docstring rules:

docstring-convention = "google"

timeout: int = 1
"""Timeout.

Attributes:
    timeout (str):
"""

Options

None.