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.

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.