private-class-attribute-owner-docstring-forbidden (PDF514)¶

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.

Rule is incompatible with PDF522.

What it does¶

Checks for private attributes documented in class docstring attribute documentation.

PDF514 checks Google Attributes sections, NumPy Attributes sections, and reStructuredText :ivar:, :cvar:, :var:, and :vartype: fields when the matching convention is active. Attribute names beginning with _ are private, including dunder-style names such as __slots__.

The rule checks parsed primary class docstrings only. It does not require the private attribute to exist in the class inventory, and it reports repeated private entries independently. Nested class docstrings are checked as their own class docstrings. Module docstrings, function docstrings, and additional string literals after a primary class docstring are not class owner docstrings for this rule.

PDF514 forbids private class attributes in class docstring attribute entries regardless of whether the attribute exists. If the project instead wants private class attributes documented as attached docstrings, use PDF523; if it wants private class attributes documented in owner docstrings, use PDF522 and do not enable PDF514.

Why is this useful?¶

Private attributes are implementation details and should usually stay out of owner docstrings that describe the public class API.

Ruff compatibility¶

None.

Examples¶

A private class attribute documented in the class docstring is reported:

docstring-convention = "google"

class Client:
    """HTTP client.

    Attributes:
        _token (str): Internal token.
        timeout (float): Request timeout.
    """

    _token: str
    timeout: float

PDF514: Line 5: Class docstring documents private attribute '_token'

NumPy and reStructuredText attribute entries are checked under their active conventions:

docstring-convention = "numpy"

class Client:
    """HTTP client.

    Attributes
    ----------
    _token, timeout, __slots__ : object
        Client state.
    _token : str
        Repeated internal token.
    """

PDF514: Line 6: Class docstring documents private attribute '_token'
PDF514: Line 6: Class docstring documents private attribute '__slots__'
PDF514: Line 8: Class docstring documents private attribute '_token'

reStructuredText attribute value and type fields are checked under the rest convention:

docstring-convention = "rest"

class Client:
    """HTTP client.

    :ivar _token: Internal token.
    :vartype _cache: dict[str, object]
    :ivar timeout: Request timeout.
    """

PDF514: Line 4: Class docstring documents private attribute '_token'
PDF514: Line 5: Class docstring documents private attribute '_cache'

Nested class docstrings are checked independently:

docstring-convention = "google"

class Outer:
    """Outer client.

    Attributes:
        _outer: Outer state.
    """

    class Inner:
        """Inner client.

        Attributes:
            _inner: Inner state.
        """

PDF514: Line 5: Class docstring documents private attribute '_outer'
PDF514: Line 12: Class docstring documents private attribute '_inner'

Only primary class docstrings are checked. Module docstrings, function docstrings, and later string literals are ignored by PDF514:

docstring-convention = "google"

"""Module.

Attributes:
    _module_token: Internal token.
"""

class Client:
    """HTTP client."""

    """Attributes:
    _class_token: Internal token.
    """

    def configure(self):
        """Configure.

        Attributes:
            _function_token: Internal token.
        """

Private attribute-looking text is ignored when the active convention does not parse it as attribute documentation:

docstring-convention = "pep257"

class Client:
    """HTTP client.

    Attributes:
        _token (str): Internal token.
    """

Options¶

None.