signature-annotations
LintFlags a signature parameter or a value-returning function that carries no type annotation.
restated-types
A name (type): description entry restates in prose what an annotated signature states in code, and only one of the two is checked. A type checker reads the annotation on every run whereas nothing reads the docstring type, so the written copy can stay wrong for the life of the function. The renderers that surface a docstring surface the signature beside it anyway, an editor hover and help() both printing the parameter list above the body.
An entry resolves against the definition whose body its docstring opens. A parameter-documenting section reads the enclosing function's parameters, the *args and **kwargs variadics included, since an entry name drops its star prefix before it resolves. An Attributes: section reads the class body's annotated fields. Google style spells the parameter heading several ways, so Args:, Arguments:, Parameters:, Keyword Args:, Keyword Arguments:, Other Args:, Other Arguments:, Other Params:, and Other Parameters: all document parameters alike.
The report holds back wherever the docstring is carrying its own weight. A parameter with no annotation leaves the docstring as the only place its type is written, which is the gap
pushes into the code instead. An entry naming no member of the set its section documents resolves against nothing, so aReturns: or Raises: entry that happens to share a parameter's name stays silent. A module docstring documents no signature and no class body, leaving every entry inside it unresolved.Nothing here is rewritten, because deciding which of two disagreeing types is correct needs a reader rather than a formatter.
Configuration
| Key | Type | Default | Meaning |
|---|---|---|---|
enabled | bool | true | Toggles the rule on or off. |
The Canonical Case
Both Args: entries name a parameter the signature annotates, so each parenthesized type group draws a report anchored on the group itself rather than on the whole entry. A type checker reads the annotation on every run whereas nothing reads the docstring type, leaving the prose free to describe what the parameter is for.
def dial(host: str, timeout: float) -> Session:
"""
Open a session against a remote.
Args:
host (str): The remote to dial.
timeout (float): Seconds before the dial is abandoned.
"""More Examples
An entry name drops its * or ** prefix before it resolves, so *args and **kwargs reach the annotated variadics the signature declares.
host is annotated in the class body and draws a report. port is bound by a plain assignment carrying no annotation and proxy is declared nowhere, so both stay silent.
No Change
Only a parameter-documenting section resolves against the signature, so an entry that happens to share a parameter's name under another heading stays silent.
No Change
The same entries under a signature carrying no annotations stay silent, because the docstring is then the only place the type is written.
Related
For per-line opt-outs, the Suppression chapter covers the # prose: ignore[restated-types] directive.