New submission from Peilonrayz firstname.lastname@example.org:
The documentation for `typing.overload` says in a non-stub file the last definition shouldn't be typed. However running that through `mypy --strict` fails. I opened an issue on mypy a couple of days ago, however was told to report this on CPython.
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=... ``` 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=bfadffe92571b4faa... ``` 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
Change by Ken Jin email@example.com:
---------- nosy: +gvanrossum, kj, levkivskyi versions: -Python 3.6, Python 3.7
Ken Jin firstname.lastname@example.org added the comment:
Apologies to all for the spam, I made a misclick.
Maybe the documentation could be clearer for that specific example. The following code seems to work on mypy (in a non-stub file): ``` from typing import overload, Any, Optional
@overload def utf8(value: None) -> None: ... @overload def utf8(value: bytes) -> bytes: ... def utf8(value: Optional[bytes]) -> Optional[bytes]: if value is None: return None return b'' ``` But I don't know if that's the intended usage, because that makes overload appear rather redundant.
---------- versions: +Python 3.10, Python 3.8, Python 3.9 -Python 3.6, Python 3.7
Guido van Rossum email@example.com added the comment:
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
Peilonrayz firstname.lastname@example.org added the comment:
Thank you for the insight Guido. Sorry to be a bother everyone.
---------- resolution: not a bug -> versions: +Python 3.6, Python 3.7