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: Every semantic violation kind has a correction, but instance-specific safety can prevent a fix.
  • Sometimes: At least one semantic violation kind is intentionally diagnostic-only while others have fixes.
  • 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 opt-in: 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.

The Source contexts column shows whether a rule applies to complete Python modules, standalone fragments, or both. Context applicability is a hard semantic boundary; exact rule selection does not restore an inapplicable rule.

PCF: pydocformatter comment formatting

Code Name Summary Fix available Enabled Source contexts
PCF000 standalone-comment-formatting Standalone comment needs formatting Usually By default Module and Fragment
PCF001 trailing-comment-spacing Trailing comment spacing should be normalized Always By default Module and Fragment
PCF002 trailing-comment-extraction Trailing comment should be extracted Usually By default Module and Fragment
PCF100 comment-directive-normalization Directive comment should be normalized Always By default Module and Fragment
PCF101 unused-suppression Suppression selector is invalid, unknown, or unused Never By default Module and Fragment
PCF102 rule-codes-in-suppression-comments Suppression comment should use rule names instead of codes Sometimes Requires explicit Module and Fragment
PCF103 rule-names-in-suppression-comments Suppression comment should use rule codes instead of names Sometimes Requires explicit Module and Fragment
PCF200 comment-ascii-only Comment contains non-ASCII characters Never Requires explicit Module and Fragment
PCF201 comment-suspicious-unicode Comment contains suspicious Unicode Sometimes By default Module and Fragment

PDF: pydocformatter docstring formatting

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