repeated-section (PDF408)¶
Part of the PDF rule category.
View source · View documentation source · Search issues
Fix is not available.
Rule is disabled if docstring-convention is none or pep257.
What it does¶
PDF408 reports recognized Google and NumPy sections, plus non-named reST fields under the reST convention, that repeat within one docstring under the active convention. The first occurrence is allowed, and each later matching item is reported.
Known spelling variants for the same section are treated as repeats, such as Google Args and Arguments, Google Example and Examples, Google Return and Returns, Google Warning and Warnings, or NumPy Other Parameters and Other Params. Matching is case-insensitive. Google Warns documents emitted warnings and is distinct from the Warning/Warnings admonition sections.
Named reST parameter, attribute, exception, and named type field repetition is handled by PDF412 instead.
The rule only considers syntax that is recognized by the active convention. Google-style recognition is used only when docstring-convention = "google", NumPy-style recognition is used only when docstring-convention = "numpy", and reST fields are recognized only when docstring-convention = "rest". For example, a repeated NumPy-only Parameters section is ignored under the Google convention, and a Google-style Parameters: line is ignored under the NumPy convention.
PDF408 is diagnostic only. It does not merge repeated sections or otherwise rewrite the docstring.
Why is this useful?¶
Repeated sections split related documentation across multiple places, make convention-aware parsing ambiguous, and can hide later documentation from tools that expect one section of each semantic kind.
Ruff compatibility¶
None.
Examples¶
PDF408 reports repeated Google sections:
docstring-convention = "google"
def value(arg):
"""Return the value.
Args:
arg: The value.
Args:
arg: More detail.
"""
PDF408: Line 7: Docstring section 'Args' repeats earlier section 'Args'
Every repeat after the first matching section is reported:
docstring-convention = "google"
def value(arg):
"""Return the value.
Args:
arg: The value.
Args:
arg: More detail.
Args:
arg: Even more detail.
"""
PDF408: Line 7: Docstring section 'Args' repeats earlier section 'Args'
PDF408: Line 10: Docstring section 'Args' repeats earlier section 'Args'
Google spelling variants for the same semantic section are also reported:
docstring-convention = "google"
def value(arg):
"""Return the value.
Args:
arg: The value.
Arguments:
arg: More detail.
"""
PDF408: Line 7: Docstring section 'Arguments' repeats earlier section 'Args'
Several alias families may be reported in one docstring:
docstring-convention = "google"
def value(arg):
"""Return the value.
Example:
value(1)
Examples:
value(2)
Return:
int: The value.
Returns:
int: More detail.
Warning:
The value may be approximate.
Warns:
RuntimeWarning: If the value is approximate.
Warnings:
UserWarning: If the value is approximate.
"""
PDF408: Line 7: Docstring section 'Examples' repeats earlier section 'Example'
PDF408: Line 13: Docstring section 'Returns' repeats earlier section 'Return'
PDF408: Line 22: Docstring section 'Warnings' repeats earlier section 'Warning'
Different recognized sections are allowed, even when they share a related role or the same order rank:
docstring-convention = "google"
def value(arg, option):
"""Return the value.
Args:
arg: The value.
Keyword Args:
option: The option.
"""
Google section headers are still recognized if a separate style rule would add a missing colon:
docstring-convention = "google"
def value(arg):
"""Return the value.
Args
arg: The value.
Args:
arg: More detail.
"""
PDF408: Line 7: Docstring section 'Args' repeats earlier section 'Args'
Section-like text inside protected structures is not counted when that structure parser is enabled:
docstring-convention = "google"
def value(arg):
"""Return the value.
Example::
Args:
arg: This is literal example text.
Args:
arg: The value.
"""
If the relevant docstring-parse-* protection is disabled, the same section-like text can be parsed as a section and later repeats can be reported:
docstring-convention = "google"
docstring-parse-literal-blocks = false
def value(arg):
"""Return the value.
Example::
Args:
arg: This is literal example text.
Args:
arg: The value.
"""
PDF408: Line 9: Docstring section 'Args' repeats earlier section 'Args'
PDF408 also reports repeated NumPy sections:
docstring-convention = "numpy"
def value(arg):
"""Return the value.
Parameters
----------
arg : int
The value.
Parameters
----------
option : int
The option.
"""
PDF408: Line 9: Docstring section 'Parameters' repeats earlier section 'Parameters'
NumPy spelling variants for the same section are reported:
docstring-convention = "numpy"
def value(arg):
"""Return the value.
Other Parameters
----------------
arg : int
The value.
Other Params
------------
option : int
The option.
"""
PDF408: Line 9: Docstring section 'Other Params' repeats earlier section 'Other Parameters'
PDF408 also reports repeated non-named reST fields under the reST convention:
docstring-convention = "rest"
def value(arg):
"""Return the value.
:returns: The value.
:return: More detail.
"""
PDF408: Line 5: Docstring field ':return:' repeats earlier field ':returns:'
Non-named type fields and unknown fields repeat within their own field family:
docstring-convention = "rest"
def value(arg):
"""Return the value.
:rtype: int
:rtype: str
:meta private: yes
:meta public: yes
:meta private: still private
"""
PDF408: Line 5: Docstring field ':rtype:' repeats earlier field ':rtype:'
PDF408: Line 8: Docstring field ':meta private:' repeats earlier field ':meta private:'
Repeated named reST entries are handled by PDF412 instead:
docstring-convention = "rest"
def value(arg):
"""Return the value.
:param arg: The value.
:parameter arg: More detail.
"""
Convention recognition matters. A Google-style colon section is not counted as a NumPy section:
docstring-convention = "numpy"
def value(arg):
"""Return the value.
Parameters:
arg: The value.
Parameters
----------
arg : int
More detail.
"""
PDF408 reports repeated sections in non-simple docstring literals, but still does not fix them:
docstring-convention = "google"
def value(arg):
("Return the value.\n\n"
"Args:\n"
" arg: The value.\n\n"
"Args:\n"
" arg: More detail.")
PDF408: Lines 2-6: Docstring section 'Args' repeats earlier section 'Args'
Options¶
None.