Skip to content

missing-public-dunder-method-documentation (PDF612)

Added in 1.0.0 Never fix Requires explicit

Part of the PDF rule category.

View source · View documentation source · Search issues

Fix is not available.

Rule must by default be explicitly selected, unless it is removed from require-explicit.

What it does

Checks for public dunder methods that are missing docstrings.

The rule checks methods whose names start and end with double underscores. It excludes __init__, which is handled by PDF614 and PDF615. A dunder method is public when its containing class and containing module path are public.

Why is this useful?

Dunder methods define protocol behavior and often need documentation when a project opts into that policy.

Ruff compatibility

This rule replaces Ruff's D105, but uses “dunder” terminology and excludes __init__.

Examples

A public dunder method without a docstring is reported:

class Client:
    """Client."""

    def __str__(self):
        return "client"

PDF612: Line 4: Public dunder method 'Client.__str__' is missing docstring

Async dunder methods are checked the same way:

class Client:
    """Client."""

    async def __aenter__(self):
        return self

PDF612: Line 4: Public dunder method 'Client.__aenter__' is missing docstring

__init__ is intentionally excluded:

class Client:
    """Client."""

    def __init__(self):
        pass

Names must have both leading and trailing double underscores:

class Client:
    """Client."""

    def __helper(self):
        pass

    def helper__(self):
        pass

Private owner chains are handled by PDF613 instead:

class _Client:
    """Client."""

    def __str__(self):
        return "client"

Options