missing-public-module-attribute-documentation (PDF510)¶
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, and ignored by broad selectors under google, numpy, and rest.
What it does¶
Checks that public module attributes are documented either in the module docstring attribute documentation or by an adjacent attribute docstring.
The rule compares supported module-level assignments against names documented in Google Attributes sections, NumPy Attributes sections, reStructuredText :ivar:, :cvar:, :var:, and :vartype: fields, and adjacent attribute docstrings. Module assignments, annotated assignments, multi-target assignments, and tuple-unpacked assignment leaves are inventoried. Private module attributes are never required.
PDF510 checks whether public module attributes have any recognized documentation. It does not care whether that documentation is in the module docstring or attached to the assignment; use PDF520 or PDF521 for a location policy, PDF511 for stale module docstring entries, and PDF513 for duplicated module attribute documentation.
PDF510 is ignored by broad selectors under parsed docstring conventions, so select PDF510 exactly under google, numpy, or rest to opt into this module-level check. With the default public-only setting, files named like private modules or private packages are skipped.
Why is this useful?¶
Module attribute documentation can otherwise drift from exported module state.
Ruff compatibility¶
None.
Examples¶
Missing public module attribute documentation is reported when a module has attribute documentation but omits a public module attribute:
docstring-convention = "google"
"""Client defaults.
Attributes:
timeout (float): Request timeout.
"""
timeout: float
retries: int
PDF510: Line 8: Public module attribute 'retries' is missing docstring documentation
An empty recognized Attributes section still opts the module into missing attribute checks:
docstring-convention = "google"
"""Client defaults.
Attributes:
"""
timeout: float
PDF510: Line 6: Public module attribute 'timeout' is missing docstring documentation
Adjacent module attribute docstrings document their assignments, including every simple target in a multi-target assignment and supported tuple-unpacked assignment. Private module attributes are not required:
docstring-convention = "google"
timeout: float
"""Request timeout."""
retries: int
PDF510: Line 4: Public module attribute 'retries' is missing docstring documentation
docstring-convention = "google"
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"
"""Client defaults.
Attributes
----------
primary, fallback : str
Request endpoints.
"""
primary = fallback = "https://example.com"
retries: int
PDF510: Line 10: Public module attribute 'retries' is missing docstring documentation
reStructuredText attribute fields are parsed under the rest convention:
docstring-convention = "rest"
"""Client defaults.
:ivar timeout: Request timeout.
"""
timeout: float
retries: int
PDF510: Line 7: Public module attribute 'retries' is missing docstring documentation
The non-summary-docstrings policy reports missing attributes for public modules whose docstring has more than a summary, even without an attribute section:
docstring-convention = "google"
docstring-missing-documentation = "non-summary-docstrings"
"""Client defaults.
Used by the transport layer.
"""
timeout: float
PDF510: Line 6: Public module attribute 'timeout' is missing docstring documentation
Options¶
docstring-missing-documentation: Controls whether missing module attribute documentation is reported only when attribute documentation already exists, for non-summary module docstrings, or for all eligible module docstrings.docstring-missing-documentation-public-only: Skips private module paths for broad missing-module-attribute checks when enabled.