Add type stubs document #844
Conversation
This was originally intended to become a stub and was written by: Sebastian Rittau <sebastian.rittau@zfutura.de> Rebecca Chen <rechen@google.com> Teddy Sudol <tsudol@google.com> Jelle Zijlstra <jelle.zijlstra@gmail.com> Also, remove unnecessary modindex link from main index.
|
At the moment, this is a 1:1 copy of the proposed PEP, minus the header. I want to iterate on that in future PRs, but for now I wanted to have a pristine copy of our last version in the history. |
|
Cf. srittau/peps#102, cc @JelleZijlstra, @rchen152, @Solumin |
|
|
||
| import X | ||
| from Y import X | ||
| from Y import X as OtherX |
There was a problem hiding this comment.
I thought from Y import X as OtherX would re-export. What is the rationale for not re-exporting in this case? If you don't want to re-export, you can always do from Y import X as _OtherX, which most stubs in typeshed already do in this case.
There was a problem hiding this comment.
It used to re-export, this was changed / clarified in PEP 484 somewhat recently (python/peps#1630). The reason is more relevant for .py than it is for .pyi — basically to better match the people's reexport intentions in the wild — but the discussion was here: https://mail.python.org/archives/list/typing-sig@python.org/thread/YLJPWECBNPD2K4TRIBRIPISNUZJCRREY/#FPTLFORIBPKY36UO7PLO47HJDCLG2KD5
There was a problem hiding this comment.
So the rule is now simpler than ever before, as always re-exports?
There was a problem hiding this comment.
as only re-exports, if the alias is the same as the original name.
| Then ``foo`` will export ``bar`` when one of the following constructs is used in | ||
| ``__init__.pyi``:: |
There was a problem hiding this comment.
It might be good to emphasize that there is no good way to avoid re-exporting. For example, tkinter/__init__.py has some methods that accept tkinter.font.Font objects, even though import tkinter does not import tkinter/font.py. As far as I know, there's no way to express this in the type system, and mypy thinks that import tkinter also loads tkinter.font even though it doesn't.
| Currently, positional-only argument syntax (PEP 570 [#pep570]_), | ||
| unions using the pipe operator (``|``) (PEP 604 [#pep604]_), | ||
| ``ParamSpec`` (PEP 612 [#pep612]_), and ``TypeAlias`` (PEP 613 [#pep613]_) | ||
| are not supported by all type | ||
| checkers and should not be used in stubs. |
There was a problem hiding this comment.
Even though documentation shouldn't be used when it is outdated, I don't think it's great if the documentation is outdated the moment it is created :)
I think it would be better to either explain when | unions should be used, or wait until we can just always use them in typeshed. Not all stubs go to typeshed, but it just doesn't make much sense to me to intentionally have more or less official documentation disagreeing with typeshed's practices.
| Use ``float`` instead of ``Union[int, float]``. | ||
| Use ``None`` instead of ``Literal[None]``. | ||
| For argument types, | ||
| use ``bytes`` instead of ``Union[bytes, memoryview, bytearray]``. |
There was a problem hiding this comment.
I think this needs a bit more explaining, or a link to somewhere where it's documented, since it does not match runtime behaviour:
>>> isinstance(bytearray(), bytes)
False
There was a problem hiding this comment.
This should probably be more prominent in the rest of the typing documentation (it is explained in the typing module docs), but the style guide is not really the correct place to explain it, just as float == float | int is not explained.
| Avoid ``Union`` return types, since they require ``isinstance()`` checks. | ||
| Use ``Any`` if necessary. |
There was a problem hiding this comment.
Maybe this part should mention the str | Any trick. A return type like str | Any means that it is not an error to treat the return value as a string, and you always have to allow it to be a string, but it could be something else too.
|
Thank you for your comments. I will revisit them once this gets merged. For the time being, I want to merge this "as is" to have a "pristine" version in the git history. |
Become a PEP maybe? What happened to this PEP? Did it never become a PEP? I'm mostly worried about having outdated information in a PEP that shows up in google searches. |
|
Yes, we intended to submit it as a PEP, but never did because we couldn't find a sponsor. The typing docs are now probably a better fit. The PEP is unlikely to show up in Google searches because it just existed in @srittau's repo. |
This was originally intended to become a stub and was written by:
Sebastian Rittau sebastian.rittau@zfutura.de
Rebecca Chen rechen@google.com
Teddy Sudol tsudol@google.com
Jelle Zijlstra jelle.zijlstra@gmail.com
Also, remove unnecessary modindex link from main index.