bpo-35581: Document @typing.type_check_only #11312
Conversation
|
|
||
| Decorator to mark a class or function to be unavailable at runtime. | ||
|
|
||
| This decorator is itself not available at runtime. It is mainly |
There was a problem hiding this comment.
TBH, I am not sure we need to document something not actually available at runtime here.
There was a problem hiding this comment.
A bit of a meta ramble: One of the problems is that there is not central "typing documentation". Most things are described in PEP 484, the typing documentation and mypy's documentation and there is a significant overlap, but some things are only described in one of them. The typeshed CONTRIBUTING file has a bit more stuff, too. Although by now I'd describe myself as fairly experienced regarding typing, I am still always looking for the right document when I encounter a corner case or want to link someone the documentation.
In the long term we should probably have a comprehensive guide on https://docs.python.org/ and link to that from the other documentation. But until that is the case, I don't think PEP 484 should be the only place where this is documented. And while it is not available at runtime, @type_check_only is imported from typing, so its documentation is where I would look for it.
|
|
||
| def fetch_response() -> Response: ... | ||
|
|
||
| Note that returning instances of private classes is not recommended. |
There was a problem hiding this comment.
Even if we decide that documenting this makes sense, providing an example that is not recommended is a bad idea. I would instead provide a more realistic example. IIUC a typical situation for this would be a private protocol for argument types. Protocols are not accepted yet, so maybe this should wait until they are?
There was a problem hiding this comment.
In my experience, returning instances of private classes is a pretty common occurence. There are multiple examples of it in the standard library, the IO classes as well as Pattern and Match being the most prominent.
|
Thanks @srittau for the PR, and @gvanrossum for merging it 🌮🎉.. I'm working now to backport this PR to: 3.7. |
(cherry picked from commit 1e82954) Co-authored-by: Sebastian Rittau <srittau@rittau.biz>
|
GH-12813 is a backport of this pull request to the 3.7 branch. |
https://bugs.python.org/issue35581