pydocstyle D401: First line should be in imperative mood

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 module docstring as the first statement in the file. D100 means a public module has no docstring. Write one triple-quoted summary at the very top of the file (after any shebang or encoding comment), then re-run pydocstyle. If the module should stay undocumented, rename it with a leading underscore or add D100 to the ignore list.

D100: Missing docstring in public module

1. Reproduce:

   pydocstyle path/to/module.py

   Expected: path/to/module.py:1: D100: Missing docstring in public module.

2. Add the docstring as the first statement in the file:

   """Utilities for rendering the docs sitemap."""
   
   import os

3. Re-run:

   pydocstyle path/to/module.py

   Expected: no output, which means the file is clean.

4. If the module is intentionally undocumented (a script entry point, a test helper), silence the rule in setup.cfg instead:

   [pydocstyle]
   ignore = D100

Use this when

• pydocstyle reports D100 on a module file
• CI fails the docs-lint step with missing-docstring codes
• You are bringing a legacy codebase up to docstring conventions

Not for this skill when

• The missing docstring is on a function or class - those are D103 and D101, different fixes
• The file is a private module (leading underscore) - pydocstyle already skips it
• You use a different docstring linter - the code letters differ per tool

Variant phrasings

• "pydocstyle D100"
• "Missing docstring in public module"
• "pydocstyle missing module docstring"

Why it happens

pydocstyle treats every module without a leading underscore as public API surface, and public surface needs a docstring under its conventions. A file that starts directly with imports or code has no docstring statement, so the check fires on line 1.

Edge cases

• The docstring must be a bare string expression, not assigned to a variable; a lone triple-quoted string on its own line is what counts.
• __init__.py files are modules too and get D100 when they have no docstring.
• A shebang or encoding comment may precede the docstring, but nothing else can.

Provenance

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

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

Thread query: pydocstyle "D100: Missing docstring in public module"

TL;DR:

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: