entry-description-trailing-period (PDF308)¶
Part of the PDF rule category.
View source · View documentation source · Search issues
Fix is sometimes available.
Rule is disabled if docstring-convention is none or pep257, and ignored by broad selectors under google.
What it does¶
Checks that parsed docstring entry descriptions end with a period.
PDF308 checks Google, NumPy, and reStructuredText entries when the active convention parses them. It targets parameter, return, yield, exception, attribute, and method entry descriptions. For entries with multiline descriptions, the target is the final non-empty parsed description line. Protected nested structures such as lists and fenced code blocks are not folded into the entry description target.
Empty descriptions, generic reST fields, and reST type-only fields such as :type:, :rtype:, :ytype:, and :vartype: are skipped. Descriptions ending with a backslash are also skipped so path-like examples are not rewritten. The automatic fix only inserts a period at the end of the trimmed description target; descriptions ending with ,, ?, !, :, ;, or \u2026 are reported but not changed because appending another period would produce questionable punctuation.
Unsafe source mappings are reported but not changed. This includes docstrings whose relevant logical text is formed through evaluated escape sequences and cannot be mapped cleanly back to one source slice.
Why is this useful?¶
Consistent entry description punctuation makes section bodies read like complete prose.
Ruff compatibility¶
None.
Examples¶
Missing periods are inserted at the end of parsed entry descriptions:
docstring-convention = "google"
def connect(timeout):
"""Connect.
Args:
timeout: timeout in seconds
"""
def connect(timeout):
"""Connect.
Args:
timeout: timeout in seconds.
"""
Google return and exception entry descriptions are checked the same way:
docstring-convention = "google"
def connect(timeout):
"""Connect.
Returns:
bool: whether connection succeeded
Raises:
TimeoutError: if the connection times out
"""
def connect(timeout):
"""Connect.
Returns:
bool: whether connection succeeded.
Raises:
TimeoutError: if the connection times out.
"""
For multiline descriptions, only the final non-empty parsed description line receives the inserted period:
docstring-convention = "google"
def connect(timeout):
"""Connect.
Args:
timeout:
timeout in
seconds
"""
def connect(timeout):
"""Connect.
Args:
timeout:
timeout in
seconds.
"""
Nested protected structures do not become part of the description target:
docstring-convention = "google"
def connect(mode):
"""Connect.
Args:
mode: choose one
- fast
- safe
timeout: timeout in seconds.
"""
def connect(mode):
"""Connect.
Args:
mode: choose one.
- fast
- safe
timeout: timeout in seconds.
"""
NumPy and reStructuredText entry descriptions are checked when those conventions are active:
docstring-convention = "numpy"
def connect(timeout):
"""Connect.
Parameters
----------
timeout : int
timeout in seconds
Returns
-------
bool
whether connection succeeded
"""
def connect(timeout):
"""Connect.
Parameters
----------
timeout : int
timeout in seconds.
Returns
-------
bool
whether connection succeeded.
"""
docstring-convention = "rest"
def connect(timeout):
"""Connect.
:param timeout: timeout in seconds
:returns: whether connection succeeded
"""
def connect(timeout):
"""Connect.
:param timeout: timeout in seconds.
:returns: whether connection succeeded.
"""
Descriptions ending with non-period punctuation are reported but not changed:
docstring-convention = "google"
def connect(timeout, retries):
"""Connect.
Args:
timeout: timeout in seconds?
retries: retry count;
"""
PDF308: Line 5: Docstring entry description should end with a period
PDF308: Line 6: Docstring entry description should end with a period
Descriptions ending with a backslash are skipped:
docstring-convention = "google"
def connect(path):
"""Connect.
Args:
path: base path \\
"""
reST type-only fields, empty descriptions, and generic fields are skipped:
docstring-convention = "rest"
def connect(timeout):
"""Connect.
:param timeout:
:type timeout: int
:meta private: generated
"""
Safely mapped escapes elsewhere in the docstring do not prevent a source-local fix:
docstring-convention = "google"
def connect(timeout):
"""Connect \u2603.
Args:
timeout: timeout in seconds
"""
def connect(timeout):
"""Connect \u2603.
Args:
timeout: timeout in seconds.
"""
Options¶
None.