[issue42169] Apparently all documentation on @typing.overload is wrong
New submission from Peilonrayz
import typing help(typing.overload) Help on function overload in module typing:
overload(func) Decorator for overloaded functions/methods. In a stub file, place two or more stub definitions for the same function in a row, each decorated with @overload. For example: @overload def utf8(value: None) -> None: ... @overload def utf8(value: bytes) -> bytes: ... @overload def utf8(value: str) -> bytes: ... In a non-stub file (i.e. a regular .py file), do the same but follow it with an implementation. The implementation should *not* be decorated with @overload. For example: @overload def utf8(value: None) -> None: ... @overload def utf8(value: bytes) -> bytes: ... @overload def utf8(value: str) -> bytes: ... def utf8(value): # implementation goes here ``` The typing docs and PEP 484 say similar things. typing docs - https://docs.python.org/3/library/typing.html#typing.overload PEP 484 - https://www.python.org/dev/peps/pep-0484/#function-method-overloading Jelle Zijlstra told me to report this here. https://github.com/python/mypy/issues/9633#issuecomment-716201251
You should annotate the implementation. The example in the typing docs should perhaps also add an annotation, but that's an issue for the CPython repo, not for mypy.
Either way mypy errors which can be seen in the following playgrounds.
docs - https://mypy-play.net/?mypy=latest&python=3.9&flags=strict&gist=cffb94a2de9d5d55142da5e7d960102f
```
main.py:9: error: Function is missing a type annotation
Found 1 error in 1 file (checked 1 source file)
```
proper way? - https://mypy-play.net/?mypy=latest&python=3.9&gist=bfadffe92571b4faad04ea151b2b1c54
```
main.py:3: error: An overloaded function outside a stub file must have an implementation
Found 1 error in 1 file (checked 1 source file)
```
Is all the documentation on `typing.overload` wrong - should the implementation be annotated?
----------
assignee: docs@python
components: Documentation
messages: 379754
nosy: docs@python, peilonrayz
priority: normal
severity: normal
status: open
title: Apparently all documentation on @typing.overload is wrong
versions: Python 3.10, Python 3.6, Python 3.7, Python 3.8, Python 3.9
_______________________________________
Python tracker
Change by Ken Jin
Change by Ken Jin
Ken Jin
Guido van Rossum
The documentation for `typing.overload` says in a non-stub file the last definition shouldn't be typed.
Incorrect. It doesn't say it shouldn't be *typed*, it says it shouldn't be *decorated with @overload*, which is a different thing.
The example is correct, since no annotation is the same as annotating with `Any`.
But with `mypy --strict`, no annotation causes an error, so if you are using that, you have to add *some* annotation (e.g. `Any`).
In your final example, the overloads are not redundant, since only the overloads tell the type checker that the output type corresponds to the input type.
For more information, please see Gitter (linked from the typing home page).
----------
resolution: -> not a bug
stage: -> resolved
status: open -> closed
_______________________________________
Python tracker
Peilonrayz
Change by Guido van Rossum
participants (3)
-
Guido van Rossum
-
Ken Jin
-
Peilonrayz