class-attribute-type-required (PDF713)¶

Part of the PDF rule category.

View source · View documentation source · Search issues

Fix is sometimes available.

Rule is disabled if docstring-convention is none or pep257, and ignored by broad selectors under google, numpy, and rest.

Rule is incompatible with PDF714.

What it does¶

Checks that parsed class attribute entries in owning class docstrings include documented types. It checks only entries that match inventoried class or instance attributes, including proven literal slot members; it does not require undocumented attributes to be added to the class docstring. Attached attribute docstrings are outside the scope of PDF7xx rules.

For classes that directly inherit from a configured enum-like base, the policy is inverted: present Google and reStructuredText types are reported as redundant. Dotted configured base names are resolved through unshadowed imports and aliases, while unqualified configured names match syntactically. NumPy grammar takes precedence and is not inverted.

For ordinary classes with available single-line annotations, PDF713 inserts a mapped Google type or adds a paired canonical reStructuredText :vartype: field, filling an existing empty, single-line field first. A slot-only member has no annotation source, so its missing type remains diagnostic; the first real annotated assignment of the same name supplies the normal safe fix without changing the slot's inventory position. Later redeclarations do not replace that canonical annotation source. For configured enum-like classes, PDF713 removes mapped Google types and paired reStructuredText :vartype: fields. NumPy entries, missing annotations, and source shapes that cannot be mapped safely remain diagnostic.

The rule is convention opt-in because many projects rely on class annotations instead of repeating attribute types in docstrings.

Why is this useful?¶

Projects can require class attribute type documentation while avoiding redundant enum member type text.

Ruff compatibility¶

Ruff's RUF023 and PLE0237 inspect slot order and non-slot assignments. PDF713 instead applies docstring type policy to proven slot members and can use a separate real annotation for safe insertion.

Examples¶

PDF713 canonically copies an ordinary class attribute annotation into a Google entry that has no type:

docstring-convention = "google"

class Client:
    """Client.

    Attributes:
        timeout: Timeout in seconds.
        retries (int): Retry count.
    """

    timeout: int = 1
    retries: int = 3

class Client:
    """Client.

    Attributes:
        timeout (int): Timeout in seconds.
        retries (int): Retry count.
    """

    timeout: int = 1
    retries: int = 3

Class attribute entries with types are accepted for ordinary classes:

docstring-convention = "google"

class Client:
    """Client.

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

    timeout: int = 1

Without an attribute annotation, PDF713 reports the missing docstring type but cannot infer a replacement:

docstring-convention = "google"

class Client:
    """Client.

    Attributes:
        timeout: Timeout in seconds.
    """

    timeout = 1

PDF713: Line 5: Class attribute 'timeout' docstring entry is missing a type

For configured enum-like bases, PDF713 is inverted and reports entries that include redundant types:

docstring-convention = "google"

from enum import Enum


class Color(Enum):
    """Color.

    Attributes:
        RED (int): Red value.
        BLUE: Blue value.
    """

    RED = 1
    BLUE = 2

from enum import Enum


class Color(Enum):
    """Color.

    Attributes:
        RED: Red value.
        BLUE: Blue value.
    """

    RED = 1
    BLUE = 2

NumPy entries keep their required grammar in enum-like classes, so a documented type remains accepted:

docstring-convention = "numpy"

from enum import Enum


class Color(Enum):
    """Color.

    Attributes
    ----------
    RED : int
        Red value.
    """

    RED = 1

Dotted configured enum-like base names match import aliases, while unqualified configured names are syntactic-only:

docstring-convention = "google"
docstring-class-attribute-no-type-base-classes = ["enum.Enum"]

import enum as e


class Color(e.Enum):
    """Color.

    Attributes:
        RED (int): Red value.
    """

    RED = 1

import enum as e


class Color(e.Enum):
    """Color.

    Attributes:
        RED: Red value.
    """

    RED = 1

Slot-only members are checked but have no annotation from which to build a fix. A separate real annotation of the same slot name supplies a safe insertion source:

docstring-convention = "google"

class Point:
    """Point.

    Attributes:
        x: Horizontal coordinate.
        y: Vertical coordinate.
    """

    __slots__ = ("x", "y")
    x: float

class Point:
    """Point.

    Attributes:
        x (float): Horizontal coordinate.
        y: Vertical coordinate.
    """

    __slots__ = ("x", "y")
    x: float

PDF713: Line 6: Class attribute 'y' docstring entry is missing a type

Options¶

• docstring-class-attribute-no-type-base-classes: Direct enum-like base names whose class attribute entries should not include types. Dotted names also match direct import aliases resolved statically by LibCST, and unqualified names are syntactic-only.