ruff rule ANN204 missing-return-type-special-method

[cclauss]

https://docs.astral.sh/ruff/rules/missing-return-type-special-method/

@dhruvmanila @priya-sundaram-dev, please review and help us understand how to identify which changes are unsafe.

% git checkout -b ruff-rule-ANN204-unsafe-fixes

% ruff check --select=ANN204 --statistics

154	ANN204	missing-return-type-special-method
Found 154 errors.
No fixes available (121 hidden fixes can be enabled with the `--unsafe-fixes` option).

% ruff check --select=ANN204 --fix --unsafe-fixes --silent

% ruff check --select=ANN204 --statistics

33	ANN204	missing-return-type-special-method
Found 33 errors.

% git commit -am"ruff rule ANN204 missing-return-type-private-function" && git push

% `ruff rule ANN204`
# missing-return-type-special-method (ANN204)

Derived from the **flake8-annotations** linter.

Fix is sometimes available.

## What it does
Checks that "special" methods, like `__init__`, `__new__`, and `__call__`, have
return type annotations.

## Why is this bad?
Type annotations are a good way to document the return types of functions. They also
help catch bugs when used alongside a type checker by ensuring that the types of
any returned values, and the types expected by callers, match expectations.

Note that type checkers often allow you to omit the return type annotation for
`__init__` methods, as long as at least one argument has a type annotation. To
opt in to this behavior, use the `mypy-init-return` setting in your `pyproject.toml`
or `ruff.toml` file:

```toml
[tool.ruff.lint.flake8-annotations]
mypy-init-return = true

Example

class Foo:
    def __init__(self, x: int):
        self.x = x

Use instead:

class Foo:
    def __init__(self, x: int) -> None:
        self.x = x

Options

• lint.flake8-annotations.mypy-init-return

[priya-sundaram-dev]

Reviewed ANN204 — this is the safest of the three to land, and it works differently from ANN201/202.

For special methods ruff doesn't infer from the body; it fills in the language-defined return type from a fixed table. In my repro (ruff 0.15.21):

__init__  -> None
__str__   -> str
__repr__  -> str
__len__   -> int
__bool__  -> bool

...were all fixed, while __enter__, __iter__, __hash__, __eq__ were left alone — because their type is either class-specific (__enter__ -> Self, __iter__ -> Iterator[...]) or not in the confident-set. That's exactly the split you want: the 121 with fixes are the canonical, spec-defined types (not guesses), and the ~33 without fixes are the ones a human should annotate.

Suggested play: ruff check --select=ANN204 --unsafe-fixes --fix, skim the diff (all -> None/str/int/bool), land it — this is the biggest low-risk visible dent of the ANN rollout. The leftover special methods (__enter__/__iter__/__getitem__/…) become clean Hacktoberfest tasks since each needs the class's own type.

Same "unsafe" caveat as ANN202: the label is ruff's blanket policy on annotation-adding fixes, not a signal the return types here are doubtful.

(Disclosure: I'm Priya Sundaram, an AI software agent; a human reviews my substantive work.)