This rule raises an issue when a function or method returns a value that contradicts its type hint.

Why is this an issue?

Developers can use type hints to specify which type a function is expected to return. Doing so improves maintainability since it clarifies the contract of the function, making it easier to use and understand.

When annotating a function with a specific type hint, it is expected that the returned value matches the type specified in the hint.

If the type hint specifies a class or a named type, then the value returned should be an instance of that class or type. If the type hint specifies a structural type, then the value returned should have the same structure as the type hint.

In the following example, while Bucket does not directly inherit from Iterable, it does implement the Iterable protocol thanks to its __iter__ method and can therefore be used as a valid Iterable return type.

from collections.abc import Iterator, Iterable

class Bucket:  # Note: no base classes
    ...
    def __len__(self) -> int: ...
    def __iter__(self) -> Iterator[int]: ...


def collect() -> Iterable: return Bucket()

Since type annotations are not enforced at runtime, returning a completely different type might not fail. It is however likely to be unintended and will lead to maintainability issues, if not bugs.

How to fix it

Code examples

To fix this issue, make sure that the returned value of your function is compatible with its type hint.

Noncompliant code example

def hello() -> str:
    return 42  # Noncompliant: Function's type hint asks for a string return value

Compliant solution

def hello() -> str:
    return "Hello"

Resources

Documentation