gh-149995: Update typing.py docstrings and documentation (GH-149996)
Some of these docstrings read as if they were written when typing.py was
first written, and things have evolved since then.
A few motivations:
- Call protocols protocols instead of ABCs. They are also ABCs, but the fact
they are protocols is more relevant to typing.
- Avoid recommending direct use of .__annotations__ and steer users to
annotationlib instead.
- For TypedDict, mention NotRequired before total=False since it is more
general and probably more frequently useful.
- For overloads, mention runtime use first instead of stub use. I think early on
there was talk of allowing overload only in stubs, but it is now heavily used at
runtime too and that's more likely to be relevant to users.
(cherry picked from commit f159419ae2)
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Do not mention `__annotations__` dictionaries, as this is slightly
outdated since 3.14.
Rewrite the note about possible exceptions for clarity. Also do not
mention imported type aliases, as since 3.12 aliases with the `type`
statement do not suffer from this limitation anymore.
The documentation previously stated that Concatenate is only valid
when used as the first argument to Callable, but according to PEP 612,
it can also be used when instantiating user-defined generic classes
with ParamSpec parameters.
* gh-106320: Remove private _PyInterpreterState functions (#106335)
Remove private _PyThreadState and _PyInterpreterState C API
functions: move them to the internal C API (pycore_pystate.h and
pycore_interp.h). Don't export most of these functions anymore, but
still export functions used by tests.
Remove _PyThreadState_Prealloc() and _PyThreadState_Init() from the C
API, but keep it in the stable API.
* Doc: minor change
* Revert "Doc: minor change"
This reverts commit ebfa0937c2.
* [Doc] Remove unnecessary quotes from typing (See Also section)
* [Doc] Remove unnecessary quotes from typing
---------
Co-authored-by: Victor Stinner <vstinner@python.org>
As explained in #133960, this removes most of the behavior differences with ForwardRef.evaluate.
The remaining difference is about recursive evaluation of forwardrefs; this is practically useful
in cases where an annotation refers to a type alias that itself is string-valued.
This also improves several edge cases that were previously not handled optimally. For example,
the function now takes advantage of the partial evaluation behavior of ForwardRef.evaluate() to
evaluate more ForwardRefs in the FORWARDREF format.
This also fixes#133959 as a side effect, because the buggy behavior in #133959 derives from
evaluate_forward_ref().
- Explicitly say that isinstance/issubclass do not work on non-runtime checkable
protocols.
- Move the sentence "This raises TypeError when applied to a non-protocol class". It
took me quite some time to decide what "this" was here: it refers to applying the
decorator, not to an isinstance() call.
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
It doesn't make sense to use a deprecation for evaluate_forward_ref,
as it is a new function in Python 3.14 and doesn't have compatibility
guarantees.
I considered making it throw an error if type_params it not passed and
there is no owner. However, I think this is too unfriendly for users. The
case where this param is really needed is fairly esoteric and I don't think
this case is worth the pain of forcing users to write "type_params=()".
* Replace link to historical PEP with current document on typing.python.org
* Update Doc/library/typing.rst
Co-authored-by: Ned Batchelder <ned@nedbatchelder.com>
---------
Co-authored-by: Ned Batchelder <ned@nedbatchelder.com>
