Description
Some functions can return different types depending on passed arguments. For example:
open(name, 'rb')
returnsio.BufferedReader
, whereasopen(name, 'wb')
returnsio.BufferedWriter
.
The typeshed accurately models this using @typing.overload
and typing.Literal
. However there is the case that the argument value deciding the return type cannot be determined statically, for example:
def my_open(name: str, write: bool):
with open(name, 'wb' if write else 'rb') as f:
content = f.read()
In this case typeshed currently just claims that open
returns typing.IO[Any]
, so content
ends up having the type Any
, resulting in a loss of type safety (e.g. content.startswith('hello')
will lead to a runtime error if the file was opened in binary mode, but type checkers won't be able to warn you about this because of Any
).
While typeshed could theoretically just change the return type to typing.IO[Union[str, bytes]]
, that would force all existing code bases that currently rely on Any
to type check to update their code, which is of course unacceptable.
When starting a new project I however want the strictest type stubs possible. I explicitly do not want standard library functions to return unsafe values like Any
(or the a bit less unsafe AnyOf
suggested in #566), when the return types can be modeled by a Union
.
I therefore propose the introduction of a new variable typing.STRICTER_STUBS: bool
, that's only available during type checking.
Which would allow typeshed to do the following:
if typing.STRICTER_STUBS:
AnyOrUnion = typing.Union
else:
AnyOrUnion = typing.Any
Ambiguous return types could then be annotated as e.g. -> typing.IO[AnyOrUnion[str, bytes]]
.
This would allow users to opt into stricter type stubs, if they so desire, without forcing changes on existing code bases.
CC: @AlexWaygood, @JelleZijlstra, @srittau, @hauntsaninja, @rchen152, @erictraut
P.S. Since I have seen Union
return types being dismissed because "the caller needs to use isinstance()
", I want to note that this is not true, if the caller wants to trade type safety for performance, they can always just add an explicit Any
annotation to circumvent the runtime overhead of isinstance
. Union return types force you to either handle potential type errors or explicitly opt out of type safety, which I find strongly preferable to lack of type safety by default.