Skip to content

Rules

pydocformatter rules are grouped by code prefix. Rule pages are generated from the built-in rule registry and adjacent Markdown documentation.

Rule categories

All rules

The Fix available column summarizes automatic fix availability:

  • Always: Every finding has a fix.
  • Usually: Most findings have fixes.
  • Sometimes: Only selected findings are fixable.
  • Never: The rule is diagnostic-only.

The Enabled column shows broad-selection (e.g. by the ALL selector) behavior:

  • By default: Selected by default.
  • Requires explicit: Not selected by broad selectors unless the exact rule code is also selected, because it is included in the default require-explicit setting.
  • Convention: Default selection depends on the active docstring-convention setting, with at least one convention selecting the rule by default.
  • Convention-explicit: Removed by every docstring-convention value. Ignored conventions can be restored by exact rule-code selection, while disabled conventions cannot.
  • Setting-gated: Default selection depends on a setting other than docstring-convention.

PCF: pydocformatter comment formatting

Code Name Summary Fix available Enabled
PCF001 standalone-comment-formatting Standalone comment needs formatting Usually By default
PCF002 trailing-comment-spacing Trailing comment spacing should be normalized Always By default
PCF003 comment-directive-normalization Directive comment should be normalized Always By default
PCF004 trailing-comment-extraction Trailing comment should be extracted Usually By default
PCF005 comment-ascii-only Comment contains non-ASCII characters Never Requires explicit
PCF006 unused-suppression Suppression directive is unused Never By default

PDF: pydocformatter docstring formatting

Code Name Summary Fix available Enabled
PDF000 docstring-literal-normalization Docstring literal should be normalized Usually By default
PDF001 docstring-quote-style Docstring should use triple double quotes Sometimes By default
PDF002 docstring-backslash-raw-prefix Docstring with backslashes should use a raw string prefix Sometimes By default
PDF003 docstring-ascii-only Docstring source contains non-ASCII characters Usually Requires explicit
PDF100 docstring-indentation Docstring line is incorrectly indented Always By default
PDF101 docstring-reflow Docstring chunk needs reflow Usually By default
PDF102 docstring-trailing-whitespace Non-empty docstring line has trailing whitespace Always By default
PDF103 docstring-blank-line-whitespace Blank docstring line has whitespace Always By default
PDF104 opening-quotes-whitespace Docstring has extra whitespace after opening quotes Always By default
PDF105 closing-quotes-whitespace Docstring has extra whitespace before closing quotes Always By default
PDF106 multiline-opening-quotes-same-line Multi-line docstring opening quotes should be on the same line as content Always Convention
PDF107 multiline-opening-quotes-separate-line Multi-line docstring opening quotes should be on a separate line Always Convention-explicit
PDF108 multiline-closing-quotes-same-line Multi-line docstring closing quotes should be on the same line as content Always Convention-explicit
PDF109 multiline-closing-quotes-separate-line Multi-line docstring closing quotes should be on a separate line Always By default
PDF110 one-line-docstring Docstring with one content line should be one line Always By default
PDF200 too-many-blank-lines Docstring has too many blank lines Always By default
PDF201 missing-blank-line Docstring is missing a blank line Always By default
PDF202 empty-docstring Docstring is empty Never By default
PDF203 summary-too-long Docstring summary does not fit on one line Never By default
PDF204 no-blank-line-before-function-docstring No blank lines allowed before function docstring Always By default
PDF205 blank-line-before-function-docstring One blank line required before function docstring Always Convention-explicit
PDF206 no-blank-line-after-function-docstring No blank lines allowed after function docstring Always Convention-explicit
PDF207 blank-line-after-function-docstring One blank line required after function docstring Always Convention-explicit
PDF208 no-blank-line-before-class-docstring No blank lines allowed before class docstring Always By default
PDF209 blank-line-before-class-docstring One blank line required before class docstring Always Convention-explicit
PDF210 no-blank-line-after-class-docstring No blank lines allowed after class docstring Always Convention-explicit
PDF211 blank-line-after-class-docstring One blank line required after class docstring Always By default
PDF212 missing-summary Docstring is missing a summary Never By default
PDF300 summary-trailing-period Docstring summary should end with a period Sometimes Convention
PDF301 summary-terminal-punctuation Docstring summary should end with terminal punctuation Sometimes Convention
PDF302 non-imperative-summary Docstring summary should be in imperative mood Never Convention
PDF303 signature-like-summary Docstring summary should not be a signature Never Convention
PDF304 summary-first-word-capitalization Docstring summary first word should be capitalized Sometimes By default
PDF305 summary-starts-with-this Docstring summary should not start with "This" Never Convention
PDF306 parameter-documentation-too-generic Parameter documentation is too generic Never Convention
PDF307 attribute-documentation-too-generic Attribute documentation is too generic Never Convention
PDF308 entry-description-trailing-period Docstring entry description should end with a period Sometimes Convention
PDF309 entry-description-terminal-punctuation Docstring entry description should end with terminal punctuation Sometimes Convention
PDF310 entry-description-first-word-capitalization Docstring entry description first word should be capitalized Sometimes Convention
PDF311 property-docstring-starts-with-verb Property docstring should not start with a verb Never By default
PDF400 section-name-capitalization Docstring section name should be properly capitalized Sometimes Convention
PDF401 section-name-pluralization Docstring section name should use the preferred plural or canonical form Sometimes Convention
PDF402 section-name-term-normalization Docstring section name should use the preferred equivalent term Sometimes Convention
PDF403 section-name-trailing-content Docstring section name should be followed by a line break Sometimes Convention
PDF404 section-name-trailing-colon Docstring section name should end with a colon Sometimes Convention
PDF405 section-underline-format Docstring section underline should be normalized Sometimes Convention
PDF406 empty-section Docstring section should not be empty Never Convention
PDF407 section-order Docstring sections should be in the configured order Never Convention
PDF408 repeated-section Docstring section should not be repeated Never Convention
PDF409 docstring-entry-spacing Docstring convention entry spacing should be normalized Sometimes Convention
PDF410 exception-entry-normalization Docstring exception entry should use canonical spelling Sometimes Convention
PDF411 type-like-token-spacing-normalization Docstring type-like token spacing should be normalized Sometimes Convention
PDF412 repeated-docstring-entry Docstring entry should not be repeated Never Convention
PDF413 section-name-superfluous-colon Docstring section name should not end with a colon Sometimes Convention
PDF414 malformed-convention-entry Docstring convention entry should use valid syntax Never Convention
PDF415 convention-entry-indentation Docstring convention entry should use valid indentation Never Convention
PDF500 missing-parameter-documentation Function parameter is missing docstring documentation Never Convention
PDF501 extraneous-parameter-documentation Docstring documents a parameter that is not in the function signature Never Convention
PDF502 missing-return-documentation Function return value is missing docstring documentation Never Convention
PDF503 extraneous-return-documentation Docstring has return documentation for a function that does not return Never Convention
PDF504 missing-yield-documentation Function yield value is missing docstring documentation Never Convention
PDF505 extraneous-yield-documentation Docstring has yield documentation for a function that does not yield a meaningful value Never Convention
PDF506 missing-exception-documentation Raised exception is missing docstring documentation Never Convention
PDF507 extraneous-exception-documentation Docstring documents an exception that is not explicitly raised Never Convention-explicit
PDF508 missing-public-class-attribute-documentation Public class attribute is missing docstring documentation Never Convention
PDF509 extraneous-class-attribute-documentation Class docstring documents an attribute that is not present Never Convention
PDF510 missing-public-module-attribute-documentation Public module attribute is missing docstring documentation Never Convention-explicit
PDF511 extraneous-module-attribute-documentation Module docstring documents an attribute that is not present Never Convention
PDF512 duplicate-class-attribute-documentation Attached attribute docstring duplicates class docstring attribute documentation Never Convention
PDF513 duplicate-module-attribute-documentation Attached attribute docstring duplicates module docstring attribute documentation Never Convention
PDF514 private-class-attribute-owner-docstring-forbidden Class docstring documents a private attribute Never Convention
PDF515 private-module-attribute-owner-docstring-forbidden Module docstring documents a private attribute Never Convention
PDF516 private-class-attribute-attached-docstring-forbidden Private class attribute should not have an attached docstring Never Requires explicit
PDF517 private-module-attribute-attached-docstring-forbidden Private module attribute should not have an attached docstring Never Requires explicit
PDF518 public-class-attribute-docstring-must-be-owner Public class attribute must use class docstring documentation, not attached docstring Never Requires explicit
PDF519 public-class-attribute-docstring-must-be-attached Public class attribute must use attached docstring, not class docstring documentation Never Requires explicit
PDF520 public-module-attribute-docstring-must-be-owner Public module attribute must use module docstring documentation, not attached docstring Never Requires explicit
PDF521 public-module-attribute-docstring-must-be-attached Public module attribute must use attached docstring, not module docstring documentation Never Requires explicit
PDF522 private-class-attribute-docstring-must-be-owner Private class attribute must use class docstring documentation, not attached docstring Never Requires explicit
PDF523 private-class-attribute-docstring-must-be-attached Private class attribute must use attached docstring, not class docstring documentation Never Requires explicit
PDF524 private-module-attribute-docstring-must-be-owner Private module attribute must use module docstring documentation, not attached docstring Never Requires explicit
PDF525 private-module-attribute-docstring-must-be-attached Private module attribute must use attached docstring, not module docstring documentation Never Requires explicit
PDF526 parameter-documentation-order Docstring parameters are not in function signature order Never Convention
PDF600 missing-public-package-documentation Public package is missing docstring Never By default
PDF601 missing-private-package-documentation Private package is missing docstring Never Requires explicit
PDF602 missing-public-module-documentation Public module is missing docstring Never By default
PDF603 missing-private-module-documentation Private module is missing docstring Never Requires explicit
PDF604 missing-public-class-documentation Public class is missing docstring Never By default
PDF605 missing-private-class-documentation Private class is missing docstring Never Requires explicit
PDF606 missing-public-nested-class-documentation Public nested class is missing docstring Never By default
PDF607 missing-private-nested-class-documentation Private nested class is missing docstring Never Requires explicit
PDF608 missing-public-function-documentation Public function is missing docstring Never By default
PDF609 missing-private-function-documentation Private function is missing docstring Never Requires explicit
PDF610 missing-public-method-documentation Public method is missing docstring Never By default
PDF611 missing-private-method-documentation Private method is missing docstring Never Requires explicit
PDF612 missing-public-dunder-method-documentation Public dunder method is missing docstring Never Requires explicit
PDF613 missing-private-dunder-method-documentation Private dunder method is missing docstring Never Requires explicit
PDF614 missing-public-init-documentation Public init method is missing docstring Never By default
PDF615 missing-private-init-documentation Private init method is missing docstring Never Requires explicit
PDF616 forbidden-function-docstring Function decorated with forbidden decorator should not have a docstring Never By default
PDF700 parameter-missing-description Function parameter docstring entry is missing a description Never Convention
PDF701 parameter-type-required Function parameter docstring entry is missing a type Never Convention-explicit
PDF702 parameter-type-forbidden Function parameter docstring entry should not include a type Never Convention-explicit
PDF703 parameter-type-mismatch Function parameter docstring type does not match the annotation Never Convention
PDF704 return-missing-description Function return docstring entry is missing a description Never Convention
PDF705 return-type-required Function return docstring entry is missing a type Never Convention-explicit
PDF706 return-type-forbidden Function return docstring entry should not include a type Never Convention-explicit
PDF707 return-type-mismatch Function return docstring type does not match the annotation Never Convention
PDF708 yield-missing-description Function yield docstring entry is missing a description Never Convention
PDF709 yield-type-required Function yield docstring entry is missing a type Never Convention-explicit
PDF710 yield-type-forbidden Function yield docstring entry should not include a type Never Convention-explicit
PDF711 yield-type-mismatch Function yield docstring type does not match the annotation Never Convention
PDF712 class-attribute-missing-description Class attribute docstring entry is missing a description Never Convention
PDF713 class-attribute-type-required Class attribute docstring entry is missing a type Never Convention-explicit
PDF714 class-attribute-type-forbidden Class attribute docstring entry should not include a type Never Convention-explicit
PDF715 class-attribute-type-mismatch Class attribute docstring type does not match the annotation Never Convention
PDF716 module-attribute-missing-description Module attribute docstring entry is missing a description Never Convention
PDF717 module-attribute-type-required Module attribute docstring entry is missing a type Never Convention-explicit
PDF718 module-attribute-type-forbidden Module attribute docstring entry should not include a type Never Convention-explicit
PDF719 module-attribute-type-mismatch Module attribute docstring type does not match the annotation Never Convention