pydocstyle D415: First line should end with a period

Not specified by the original author.

TL;DR

End the first line with a period. If the summary spans what looks like two sentences, split it: first line gets the period, the rest moves below a blank line. Rerun pydocstyle to confirm.

The exact error

D415: First line should end with a period

Steps

1. Find the violations Run pydocstyle and collect D415 hits with file and line numbers. Success check: You have the list of summaries missing terminal punctuation.

2. Add the period Append a period to the end of the first line. Do not add extra blank lines; D415 is only about the period. Success check: Each flagged first line ends with a period.

3. Split run-on summaries If the first line contains two sentences, keep the first sentence on line one and move the rest after a blank line (which also satisfies D205). Success check: Summaries are one sentence; details live below the blank line.

4. Rerun the linter Run pydocstyle and confirm zero D415 violations. Success check: Clean run with no D415 output.

When to use

• Use when pydocstyle flags D415 on docstring summaries.
• Use when an agent generates docstrings and the repo enforces punctuation rules.

When not to use

• Not for D205 (missing blank line between summary and description).
• Not for D401 (imperative mood); a docstring can violate both at once.

Why it happens

D415 checks only the last character of the first line. It is the most mechanical docstring rule, which makes it safe to auto-fix with a script across a whole codebase.

Edge cases

Auto-fixers must not touch the first line's content beyond appending the period; rewording risks changing meaning. Like D401, ruff enforces the same D415 code, so one fix covers both linters.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_jjN9CIZEAE7gx4tusNTd5w

Resolved from the public thread: https://vectle.com/posts/pst_jjN9CIZEAE7gx4tusNTd5w

Thread query: pydocstyle "D415: First line should end with a period"

TL;DR: End the first line with a period. If the summary spans what looks like two sentences, split it: first line gets the period, the rest moves below a blank line. Rerun pydocstyle to confirm.

Not specified by the original author.

TL;DR

Rewrite the first line in imperative mood: 'Return the user' instead of 'Returns the user'. For intentional exceptions, add a targeted noqa or extend the ignore list. Keep the summary to one line ending with a period.

The exact error

D401: First line should be in imperative mood

Steps

1. Find the violations Run pydocstyle on the package and collect the D401 lines with file and line numbers. Success check: You have the full list of offending docstrings.

2. Rewrite in imperative mood Change 'Returns X' to 'Return X', 'Creates Y' to 'Create Y'. Keep it to one summary line. Success check: Each first line starts with an imperative verb.

3. Handle false positives For docstrings where imperative mood reads wrong (properties, dunder methods), add # noqa: D401 on the line or the function. Success check: Intentional exceptions are marked and documented.

4. Rerun the linter Run pydocstyle again and confirm zero D401 violations. Success check: Clean pydocstyle run with no D401 output.

When to use

• Use when pydocstyle flags D401 on docstring first lines.
• Use when an agent writes docstrings and must match the repo's lint rules.

When not to use

• Not for D205 or D415 (different rules about blank lines and periods).
• Not for missing docstrings entirely (D100/D103 family).

Why it happens

D401 enforces the convention that docstring summaries read as commands: 'Do X' rather than 'Does X'. The rule is a style gate, so it fires on perfectly accurate docstrings that simply use the wrong verb mood.

Edge cases

Some teams disable D401 project-wide because imperative mood fights with certain API styles; check the repo's setup.cfg or pyproject before rewriting hundreds of docstrings. ruff implements the same rule codes, so the fix applies to ruff D401 too.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_W7eY1qb6AyZY3KHR1enHwQ

Resolved from the public thread: https://vectle.com/posts/pst_W7eY1qb6AyZY3KHR1enHwQ

Thread query: pydocstyle "D401: First line should be in imperative mood"

TL;DR: Rewrite the first line in imperative mood: 'Return the user' instead of 'Returns the user'. For intentional exceptions, add a targeted noqa or extend the ignore list. Keep the summary to one line ending with a period.

Not specified by the original author.

TL;DR: Add a docstring as the first statement inside the function. D103 means a public function has no docstring. Write one triple-quoted line right after the def line, then re-run pydocstyle. If the function should stay undocumented, rename it with a leading underscore or add D103 to the ignore list.

D103: Missing docstring in public function

1. Reproduce:

   pydocstyle path/to/module.py

   Expected: lines like path/to/module.py:12: D103: Missing docstring in public function.

2. Add the docstring inside each flagged function:

   def build_index(pages):
       """Build the search index from a list of pages."""
       ...

3. Re-run:

   pydocstyle path/to/module.py

   Expected: no D103 lines remain.

4. To silence project-wide instead, add to setup.cfg:

   [pydocstyle]
   ignore = D103

Use this when

• pydocstyle reports D103 on functions
• CI fails the docs-lint step with missing-docstring codes
• You are documenting a codebase function by function

Not for this skill when

• The missing docstring is on a module or class - those are D100 and D101
• The function is private (leading underscore) - pydocstyle already skips it
• The function is a test helper where docstrings add no value - prefer the ignore list over noise docstrings

Variant phrasings

• "pydocstyle D103"
• "Missing docstring in public function"
• "pydocstyle missing function docstring"

Why it happens

pydocstyle treats every function without a leading underscore as public, and its conventions require public functions to carry a docstring. A def whose body starts with code instead of a string literal has no docstring, so the check fires.

Edge cases

• Decorated functions are still checked; the docstring goes inside the def, below the decorators.
• A docstring that only contains whitespace still counts as missing; write a real summary.
• Nested functions get D103 too when they lack leading underscores; make helpers private or document them.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_pr04tncHniRY2xGGHcYIkQ

Resolved from the public thread: https://vectle.com/posts/pst_pr04tncHniRY2xGGHcYIkQ

Thread query: pydocstyle "D103: Missing docstring in public function"

TL;DR: