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.

[source,python]
----
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

[source,python,diff-id=1,diff-type=noncompliant]
----
def hello() -> str:
    return 42  # Noncompliant: Function's type hint asks for a string return value
----


==== Compliant solution

[source,python,diff-id=1,diff-type=compliant]
----
def hello() -> str:
    return "Hello"
----


== Resources

=== Documentation

* Python documentation - https://docs.python.org/3/library/typing.html[Support for type hints]
* PEP 544 - https://peps.python.org/pep-0544/[Protocols: Structural subtyping (static duck typing)]

ifdef::env-github,rspecator-view[]

'''
== Implementation Specification
(visible only on this page)

=== Message

*Return a "XXX" instead of a "YYY" or update function "ZZZ" type hint.


=== Highlighting

* If the function returns the wrong type:
** Primary: The return statement
** Secondaries: 1. the function name, 2. The type hint
* If the function might terminate without reaching a return statement:
** Primary Location: The function name
** Secondary: the type hint


endif::env-github,rspecator-view[]