Skip to content

missing-private-package-documentation (PDF601)

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 private package initializer files that are missing a module docstring.

Package checks apply only to __init__ Python source or stub files. A package path is private when any discovered package path component starts with an underscore.

Why is this useful?

Private packages can still benefit from local documentation when a project chooses to require it.

Ruff compatibility

None.

Examples

A private package initializer without a module docstring is reported:

DEFAULT_TIMEOUT = 30

PDF601: Line 1: Private package is missing docstring

An underscore-prefixed top-level package is also private:

DEFAULT_TIMEOUT = 30

PDF601: Line 1: Private package is missing docstring

A documented private package is accepted:

"""Internal client helpers."""

DEFAULT_TIMEOUT = 30

Public package paths are handled by PDF600 instead:

DEFAULT_TIMEOUT = 30

Options

None.