Settings¶

The pydocfmt check tool is configurable via the settings below. The Setting column shows the TOML key used in configuration files under [tool.pydocfmt], while the CLI column shows the corresponding pydocfmt check flag when one exists.

Use pydocfmt check --help for command-line usage and pydocfmt config for CLI-based settings help. Use pydocfmt config to directly list all available settings, and pass an additional argument specifying one of the setting names (TOML key) in order to get specific help on that setting, e.g. pydocfmt config require-explicit.

See Configuration for details on the settings loading behavior, and Settings specification for detailed settings semantics.

Run¶

output-format¶

Output format for rule findings; currently only "grouped" is supported.

• Type: grouped
• Default: "grouped"
• CLI: --output-format

[tool.pydocfmt]
output-format = "grouped"

cache¶

Whether selected disk files may reuse and populate persistent clean proofs. Disable this for diagnostics or when a cache location is not trusted.

• Type: bool
• Default: true
• CLI: --cache

[tool.pydocfmt]
cache = true

cache-dir¶

Persistent cache directory. The default is relative to the auto-discovered project configuration root, while explicitly configured values follow their normal setting source base. pydocformatter may create this directory, but it does not create missing ancestor directories; the immediate parent must already be a directory.

• Type: str
• Default: ".pydocfmt_cache"
• CLI: --cache-dir

[tool.pydocfmt]
cache-dir = ".pydocfmt_cache"

parallelism¶

File-level parallelism. Use 0 for all logical CPU cores subject to platform process-pool limits, a whole number greater than or equal to 1 for an exact worker count, or a fractional value greater than 0 and less than 1 for that ratio of logical CPU cores. Small file sets may be slower with parallelism due to process startup overhead.

• Type: float
• Default: 0.0
• CLI: --parallelism

[tool.pydocfmt]
parallelism = 0.0

Formatting¶

line-length¶

Maximum line length for docstrings and comments.

• Type: int
• Default: 88
• CLI: --line-length
• Related rules: PCF001, PCF004, PDF101, PDF110

[tool.pydocfmt]
line-length = 88

url-aware-wrapping¶

Whether comment and docstring wrapping should balance line selection around destination-bearing tokens; recognized inline markup remains atomic regardless.

• Type: bool
• Default: true
• CLI: --url-aware-wrapping
• Related rules: PCF001, PCF004, PDF101

[tool.pydocfmt]
url-aware-wrapping = true

line-ending¶

Line ending to use when rewriting files; one of "auto", "lf", "cr-lf", or "native".

• Type: auto | lf | cr-lf | native
• Default: "auto"
• CLI: --line-ending

[tool.pydocfmt]
line-ending = "auto"

indent-style¶

Generated and normalized docstring indentation style; one of "space" or "tab".

• Type: space | tab
• Default: "space"
• CLI: --indent-style
• Related rules: PDF100, PDF101, PDF103, PDF107, PDF109, PDF200, PDF201, PDF403

[tool.pydocfmt]
indent-style = "space"

indent-width¶

Generated docstring indentation width and tab expansion width used when measuring docstrings and comments.

• Type: int
• Default: 4
• CLI: --indent-width
• Related rules: PCF001, PCF004, PDF100, PDF101, PDF103, PDF107, PDF109, PDF110, PDF200, PDF201, PDF403

[tool.pydocfmt]
indent-width = 4

Docstring formatting¶

docstring-convention¶

Docstring convention; one of "none", "pep257", "google", "numpy", or "rest".

• Type: none | pep257 | google | numpy | rest
• Default: "pep257"
• CLI: --docstring-convention
• Related rules: PDF106, PDF107, PDF108, PDF205, PDF206, PDF207, PDF209, PDF210, PDF300, PDF301, PDF302, PDF303, PDF305, PDF306, PDF307, PDF308, PDF309, PDF310, PDF400, PDF401, PDF402, PDF403, PDF404, PDF405, PDF406, PDF407, PDF408, PDF409, PDF410, PDF411, PDF412, PDF413, PDF414, PDF415, PDF500, PDF501, PDF502, PDF503, PDF504, PDF505, PDF506, PDF507, PDF508, PDF509, PDF510, PDF511, PDF512, PDF513, PDF514, PDF515, PDF519, PDF521, PDF523, PDF525, PDF526, PDF700, PDF701, PDF702, PDF703, PDF704, PDF705, PDF706, PDF707, PDF708, PDF709, PDF710, PDF711, PDF712, PDF713, PDF714, PDF715, PDF716, PDF717, PDF718, PDF719

[tool.pydocfmt]
docstring-convention = "pep257"

docstring-blank-line-style¶

Blank docstring line whitespace style used by PDF103; one of "blank" or "aligned".

• Type: blank | aligned
• Default: "blank"
• CLI: --docstring-blank-line-style
• Related rules: PDF103, PDF201

[tool.pydocfmt]
docstring-blank-line-style = "blank"

docstring-blank-line-after-last-section¶

Whether PDF200 and PDF201 keep one blank line after the last recognized Google or NumPy docstring section.

• Type: bool
• Default: false
• CLI: --docstring-blank-line-after-last-section
• Related rules: PDF200, PDF201

[tool.pydocfmt]
docstring-blank-line-after-last-section = false

docstring-missing-documentation¶

When missing-documentation rules report missing documentation; one of "has-section", "non-summary-docstrings", or "all-docstrings".

• Type: has-section | non-summary-docstrings | all-docstrings
• Default: "has-section"
• CLI: --docstring-missing-documentation
• Related rules: PDF500, PDF502, PDF504, PDF506, PDF508, PDF510

[tool.pydocfmt]
docstring-missing-documentation = "has-section"

docstring-missing-documentation-public-only¶

Whether broad missing-documentation checks only apply to public API definitions; explicit relevant documentation is always checked for consistency.

• Type: bool
• Default: true
• CLI: --docstring-missing-documentation-public-only
• Related rules: PDF500, PDF502, PDF504, PDF506, PDF508, PDF510

[tool.pydocfmt]
docstring-missing-documentation-public-only = true

docstring-require-init-attribute-documentation¶

Whether class missing-attribute documentation rules require supported self.* attributes assigned in __init__; extraneous class-attribute documentation checks always treat those attributes as present.

• Type: bool
• Default: false
• CLI: --docstring-require-init-attribute-documentation
• Related rules: PDF508

[tool.pydocfmt]
docstring-require-init-attribute-documentation = false

docstring-class-attribute-no-type-base-classes¶

Direct class base names whose class attribute docstring entries should not include types for PDF713. Dotted names also match direct import aliases resolved statically by LibCST; unqualified names are syntactic-only, and transitive inheritance is not resolved.

• Type: list[str]
• Default: ["enum.Enum", "enum.IntEnum", "enum.StrEnum", "enum.Flag", "enum.IntFlag", "enum.ReprEnum"]
• CLI: --docstring-class-attribute-no-type-base-classes
• Related rules: PDF713

[tool.pydocfmt]
docstring-class-attribute-no-type-base-classes = ["enum.Enum"]

docstring-forbidden-function-decorators¶

Function decorator names whose definitions should not have docstrings. Calls are unwrapped before matching, and dotted names also match import aliases resolved statically by LibCST; unqualified names are syntactic-only.

• Type: list[str]
• Default: ["typing.overload", "typing_extensions.overload"]
• CLI: --docstring-forbidden-function-decorators
• Related rules: PDF608, PDF609, PDF610, PDF611, PDF612, PDF613, PDF614, PDF615, PDF616

[tool.pydocfmt]
docstring-forbidden-function-decorators = ["typing.overload", "typing_extensions.overload"]

docstring-optional-function-decorators¶

Function decorator names whose definitions may omit docstrings. Calls are unwrapped before matching, and dotted names also match import aliases resolved statically by LibCST; unqualified names are syntactic-only.

• Type: list[str]
• Default: ["typing.override", "typing_extensions.override"]
• CLI: --docstring-optional-function-decorators
• Related rules: PDF608, PDF609, PDF610, PDF611, PDF612, PDF613, PDF614, PDF615

[tool.pydocfmt]
docstring-optional-function-decorators = ["typing.override", "typing_extensions.override"]

docstring-property-decorators¶

Function decorator names whose definitions should be treated as properties for property-specific summary checks. Calls are unwrapped before matching, and dotted names also match import aliases and builtins resolved statically by LibCST; unqualified names are syntactic-only.

• Type: list[str]
• Default: ["builtins.property", "enum.property", "functools.cached_property", "abc.abstractproperty", "types.DynamicClassAttribute"]
• CLI: --docstring-property-decorators
• Related rules: PDF302, PDF311

[tool.pydocfmt]
docstring-property-decorators = ["builtins.property", "functools.cached_property", "project.Property"]

docstring-parse-list-items¶

Parse docstring list items as distinct structures.

• Type: bool
• Default: true
• CLI: --docstring-parse-list-items

[tool.pydocfmt]
docstring-parse-list-items = true

docstring-parse-headings¶

Parse Markdown and reStructuredText docstring headings.

• Type: bool
• Default: true
• CLI: --docstring-parse-headings

[tool.pydocfmt]
docstring-parse-headings = true

docstring-parse-doctests¶

Parse and protect doctest regions in docstrings.

• Type: bool
• Default: true
• CLI: --docstring-parse-doctests

[tool.pydocfmt]
docstring-parse-doctests = true

docstring-parse-code-fences¶

Parse and protect fenced code blocks in docstrings.

• Type: bool
• Default: true
• CLI: --docstring-parse-code-fences

[tool.pydocfmt]
docstring-parse-code-fences = true

docstring-parse-block-quotes¶

Parse Markdown block quotes in docstrings.

• Type: bool
• Default: true
• CLI: --docstring-parse-block-quotes

[tool.pydocfmt]
docstring-parse-block-quotes = true

docstring-parse-tables¶

Parse and protect Markdown and reStructuredText tables in docstrings.

• Type: bool
• Default: true
• CLI: --docstring-parse-tables

[tool.pydocfmt]
docstring-parse-tables = true

docstring-parse-directives¶

Parse reStructuredText directives and their bodies in docstrings.

• Type: bool
• Default: true
• CLI: --docstring-parse-directives

[tool.pydocfmt]
docstring-parse-directives = true

docstring-parse-literal-blocks¶

Parse and protect reStructuredText literal blocks in docstrings.

• Type: bool
• Default: true
• CLI: --docstring-parse-literal-blocks

[tool.pydocfmt]
docstring-parse-literal-blocks = true

Comment formatting¶

comment-join-standalone-lines¶

Join consecutive standalone prose comment lines before wrapping.

• Type: bool
• Default: false
• CLI: --comment-join-standalone-lines
• Related rules: PCF001

[tool.pydocfmt]
comment-join-standalone-lines = false

comment-format-list-items¶

Detect and reflow standalone comment list items with hanging indentation.

• Type: bool
• Default: true
• CLI: --comment-format-list-items
• Related rules: PCF001, PCF004

[tool.pydocfmt]
comment-format-list-items = true

comment-task-marker-mode¶

Treatment for recognized task-marker comments; one of "none", "no-wrap", or "hanging".

• Type: none | no-wrap | hanging
• Default: "no-wrap"
• CLI: --comment-task-marker-mode
• Related rules: PCF001, PCF004

[tool.pydocfmt]
comment-task-marker-mode = "no-wrap"

comment-task-markers¶

Exact uppercase task marker labels recognized before a colon; has a default value. Use an empty list to disable recognition.

• Type: list[str]
• Default: ["TODO", "FIXME", "XXX", "HACK", "BUG", "DEBUG", "NOTE", "OPTIMIZE", "REVIEW"]
• CLI: --comment-task-markers
• Related rules: PCF001, PCF004

[tool.pydocfmt]
comment-task-markers = ["TODO", "FIXME", "BUG"]

comment-preserve-headings¶

Preserve detected Markdown and reStructuredText comment headings.

• Type: bool
• Default: true
• CLI: --comment-preserve-headings
• Related rules: PCF001, PCF004

[tool.pydocfmt]
comment-preserve-headings = true

comment-preserve-doctests¶

Preserve standalone doctest comment regions.

• Type: bool
• Default: true
• CLI: --comment-preserve-doctests
• Related rules: PCF001, PCF004

[tool.pydocfmt]
comment-preserve-doctests = true

comment-preserve-code-fences¶

Preserve fenced code regions in standalone comments.

• Type: bool
• Default: true
• CLI: --comment-preserve-code-fences
• Related rules: PCF001, PCF004

[tool.pydocfmt]
comment-preserve-code-fences = true

comment-format-block-quotes¶

Detect and reflow Markdown block quotes in standalone comments.

• Type: bool
• Default: true
• CLI: --comment-format-block-quotes
• Related rules: PCF001, PCF004

[tool.pydocfmt]
comment-format-block-quotes = true

comment-preserve-tables¶

Preserve detected Markdown and reStructuredText comment tables.

• Type: bool
• Default: true
• CLI: --comment-preserve-tables
• Related rules: PCF001, PCF004

[tool.pydocfmt]
comment-preserve-tables = true

comment-preserve-directives¶

Preserve reStructuredText directives and their indented bodies.

• Type: bool
• Default: true
• CLI: --comment-preserve-directives
• Related rules: PCF001, PCF004

[tool.pydocfmt]
comment-preserve-directives = true

comment-trailing-extraction-syntax-aware¶

Whether overlong trailing-comment extraction avoids decorators, compound statement headers, arguments, and parenthesized or continuation contexts.

• Type: bool
• Default: true
• CLI: --comment-trailing-extraction-syntax-aware
• Related rules: PCF004

[tool.pydocfmt]
comment-trailing-extraction-syntax-aware = true

comment-trailing-extraction-content-aware¶

Whether overlong trailing-comment extraction avoids content that enabled standalone comment structure and code detectors, or the content-aware operator heuristic, would make unsafe to reinterpret as a standalone comment.

• Type: bool
• Default: true
• CLI: --comment-trailing-extraction-content-aware
• Related rules: PCF004

[tool.pydocfmt]
comment-trailing-extraction-content-aware = true

comment-detect-code¶

Protect standalone runs matching the indentation and leading-keyword heuristic.

• Type: bool
• Default: false
• CLI: --comment-detect-code
• Related rules: PCF001, PCF004

[tool.pydocfmt]
comment-detect-code = false

comment-detect-statements¶

Protect standalone runs containing parseable Python statements.

• Type: bool
• Default: true
• CLI: --comment-detect-statements
• Related rules: PCF001, PCF004

[tool.pydocfmt]
comment-detect-statements = true

comment-detect-expressions¶

Protect standalone runs containing nontrivial Python expressions.

• Type: bool
• Default: false
• CLI: --comment-detect-expressions
• Related rules: PCF001, PCF004

[tool.pydocfmt]
comment-detect-expressions = false

Rule selection¶

select¶

Rule selectors to enable; defaults to ["ALL"].

• Type: list[str]
• Default: ["ALL"]
• CLI: --select

[tool.pydocfmt]
select = ["ALL"]

ignore¶

Rule selectors to ignore.

• Type: list[str]
• Default: []
• CLI: --ignore

[tool.pydocfmt]
ignore = []

extend-select¶

Additional rule selectors to enable.

• Type: list[str]
• Default: []
• CLI: --extend-select

[tool.pydocfmt]
extend-select = []

require-explicit¶

Rule selectors that broad rule selectors do not enable unless an exact rule-code selector also participates; has a default value.

• Type: list[str]
• Default: ["PCF005", "PDF003", "PDF516", "PDF517", "PDF518", "PDF519", "PDF520", "PDF521", "PDF522", "PDF523", "PDF524", "PDF525", "PDF601", "PDF603", "PDF605", "PDF607", "PDF609", "PDF611", "PDF612", "PDF613", "PDF615"]
• CLI: --require-explicit

[tool.pydocfmt]
require-explicit = ["PCF005", "PDF003", "PDF516", "PDF517", "PDF518", "PDF519", "PDF520", "PDF521", "PDF522", "PDF523", "PDF524", "PDF525", "PDF601", "PDF603", "PDF605", "PDF607", "PDF609", "PDF611", "PDF612", "PDF613", "PDF615"]

per-file-ignores¶

File-pattern-specific ignored rule selectors.

• Type: dict[str, list[str]]
• Default: {}
• CLI: --per-file-ignores

[tool.pydocfmt]
per-file-ignores = {}

extend-per-file-ignores¶

Additional file-pattern-specific ignored rule selectors.

• Type: dict[str, list[str]]
• Default: {}
• CLI: --extend-per-file-ignores

[tool.pydocfmt]
extend-per-file-ignores = {}

fixable¶

Rule selectors eligible for automatic fixes; defaults to ["ALL"].

• Type: list[str]
• Default: ["ALL"]
• CLI: --fixable

[tool.pydocfmt]
fixable = ["ALL"]

unfixable¶

Rule selectors ineligible for automatic fixes.

• Type: list[str]
• Default: []
• CLI: --unfixable

[tool.pydocfmt]
unfixable = []

extend-fixable¶

Additional rule selectors eligible for automatic fixes.

• Type: list[str]
• Default: []
• CLI: --extend-fixable

[tool.pydocfmt]
extend-fixable = []

File selection¶

include¶

Glob patterns for files to include.

• Type: list[str]
• Default: ["*.py", "*.pyi", "*.pyw"]
• CLI: --include

[tool.pydocfmt]
include = ["*.py", "*.pyi", "*.pyw"]

extend-include¶

Additional include glob patterns.

• Type: list[str]
• Default: []
• CLI: --extend-include

[tool.pydocfmt]
extend-include = []

exclude¶

Glob patterns for files/directories to exclude.

• Type: list[str]
• Default: [".bzr", ".direnv", ".eggs", ".git", ".git-rewrite", ".hg", ".mypy_cache", ".nox", ".pants.d", ".pydocfmt_cache", ".pytype", ".ruff_cache", ".svn", ".tox", ".venv", "__pypackages__", "_build", "buck-out", "dist", "node_modules", "venv"]
• CLI: --exclude

[tool.pydocfmt]
exclude = [".bzr", ".direnv", ".eggs", ".git", ".git-rewrite", ".hg", ".mypy_cache", ".nox", ".pants.d", ".pydocfmt_cache", ".pytype", ".ruff_cache", ".svn", ".tox", ".venv", "__pypackages__", "_build", "buck-out", "dist", "node_modules", "venv"]

extend-exclude¶

Additional exclude glob patterns.

• Type: list[str]
• Default: []
• CLI: --extend-exclude

[tool.pydocfmt]
extend-exclude = []

respect-gitignore¶

Respect .gitignore when discovering files.

• Type: bool
• Default: true
• CLI: --respect-gitignore

[tool.pydocfmt]
respect-gitignore = true

force-exclude¶

Apply exclude rules even to files passed explicitly.

• Type: bool
• Default: false
• CLI: --force-exclude

[tool.pydocfmt]
force-exclude = false

Configuration¶

per-file-settings¶

File-pattern-specific formatter setting overrides. Rule-selection, file-selection, run-level, and rule-selection-effect settings cannot be overridden per file.

• Type: dict[str, dict[str, object]]
• Default: {}

[tool.pydocfmt]
[tool.pydocfmt.per-file-settings]
"tests/**/*.py" = { docstring-missing-documentation = "has-section" }