ruff rule ANN201 missing-return-type-undocumented-public-function

[cclauss]

https://docs.astral.sh/ruff/rules/missing-return-type-undocumented-public-function

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

% ruff check --select=ANN201 --statistics

619	ANN201	missing-return-type-undocumented-public-function
Found 619 errors.
No fixes available (260 hidden fixes can be enabled with the `--unsafe-fixes` option).

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

% ruff check --select=ANN201 --statistics

359	ANN201	missing-return-type-undocumented-public-function
Found 359 errors.

% ruff rule ANN201

missing-return-type-undocumented-public-function (ANN201)

Derived from the flake8-annotations linter.

Fix is sometimes available.

What it does

Checks that public functions and methods 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.

Example

def add(a, b):
    return a + b

Use instead:

def add(a: int, b: int) -> int:
    return a + b

Availability

Because this rule relies on the third-party typing_extensions module for some Python versions,
its diagnostic will not be emitted, and no fix will be offered if typing_extensions imports
have been disabled by the [lint.typing-extensions] linter option.

Options

• lint.typing-extensions

[priya-sundaram-dev]

Looked into this — the good news is that the ANN201 unsafe autofix is much narrower than "260 unknown changes." It only ever does one thing: add -> None, and only to functions where ruff can statically prove there is no value-returning return/yield. It deliberately leaves alone:

• functions that return a value (it can't infer the type, so it won't guess), and
• bodies that raise NotImplementedError / are pure stubs.

Quick repro (isolated, so no repo config interferes):

def implicit_none(x):        # -> gets `-> None`
    if x: print(x)
def bare_return(x):          # -> gets `-> None`
    if not x: return
    print(x)
def base_method(self):       # left ALONE (raises)
    raise NotImplementedError
def returns_value(x):        # left ALONE (returns a value)
    return x + 1

$ ruff check --isolated --select=ANN201 --fix --unsafe-fixes --diff
-def implicit_none(x):
+def implicit_none(x) -> None:
-def bare_return(x):
+def bare_return(x) -> None:
Would fix 2 errors.

So the ~260 fixes that take us 619 → 359 are all -> None additions, and the remaining 359 are genuine "returns a value, ruff won't guess the type" cases that need a human or a type checker.

Why ruff still marks the -> None fix "unsafe" (and where to be careful): it's not that the None inference is wrong — it's that -> None changes the public contract. The one class of real regressions is a base/overridable method: if def load(self): in a base class is currently unannotated and a subclass overrides it to return data, pinning the base to -> None makes the subclass Liskov-inconsistent and a type checker will now flag the subclass. Free functions and main()/CLI entrypoints are safe.

Suggested workflow to land this safely:

1. ruff check --select=ANN201 --fix --unsafe-fixes to grab all the -> None additions in one branch.
2. Run the type checker (mypy/ty) on that branch — any newly-added -> None that a checker still accepts on a leaf function is safe to keep.
3. grep the diff for -> None added to methods (params start with self/cls) and spot-check the ones whose class is subclassed elsewhere — those are the only Liskov risks.
4. For the remaining 359, split by top-level directory (data_structures/, graphs/, …) into reviewable PRs and annotate the real return types; the checker's inferred types make good starting points.

Happy to take a directory (e.g. data_structures/) as a reference PR if that helps set the pattern.

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

[priya-sundaram-dev]

Small accuracy update to my note above, now that I've tested against a current ruff (0.15.21): the ANN201 unsafe autofix is a bit smarter than "only ever adds -> None." It also infers the type of simple literal returns:

def f():            -> def f() -> None:     # no value-returning path
    pass
def g():            -> def g() -> int:      # return 5
    return 5
def h():            -> def h() -> str:      # return "x"
    return "x"
def j(x):           -> (left alone)         # return x  — type not statically known
def k():            -> (left alone)         # raise NotImplementedError

So the ~260 fixable ones aren't all None; they're None plus literal-typed returns ruff could prove. Still safe-by-construction — it never guesses when the return expression's type is unknown. The remaining ~359 value-returning ones (returns a call/variable) are the human-annotation batch. Doesn't change the sequencing I suggested, just wanted the mechanism to be exact.

[cclauss]

In this repo, we are fortunate that there is not much subclassing. The majority of subclassing from things in Python's Standard Library, like Enum, Exception, MutableMapping, NamedTuple, Protocol, TestCase, TypedDict, etc.

% git grep "class " | grep "(" # Filter out the noise...

data_structures/hashing/double_hash.py:class DoubleHash(HashTable):
data_structures/hashing/hash_map.py:class _DeletedItem(_Item):
data_structures/hashing/hash_table_with_linked_list.py:class HashTableWithLinkedList(HashTable):
data_structures/hashing/quadratic_probing.py:class QuadraticProbing(HashTable):
data_structures/linked_list/deque_doubly.py:class LinkedDeque(_DoublyLinkedBase):
geometry/geometry.py:class Circle(Ellipse):
geometry/geometry.py:class Rectangle(Polygon):
geometry/geometry.py:class Square(Rectangle):
graphs/edmonds_karp_multiple_source_and_sink.py:class MaximumFlowAlgorithmExecutor(FlowNetworkAlgorithmExecutor):
graphs/edmonds_karp_multiple_source_and_sink.py:class PushRelabelExecutor(MaximumFlowAlgorithmExecutor):

Please proceed with your data_structures/ pull request.