[Python-checkins] [3.11] gh-104010: Separate and improve docs for `typing.get_origin` and `typing.get_args` (GH-104013) (#104359)
JelleZijlstra
webhook-mailer at python.org
Wed May 10 10:49:56 EDT 2023
https://github.com/python/cpython/commit/a8e902d2c2e90255c838bd99e833cef2c674c1f0
commit: a8e902d2c2e90255c838bd99e833cef2c674c1f0
branch: 3.11
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: JelleZijlstra <jelle.zijlstra at gmail.com>
date: 2023-05-10T07:49:49-07:00
summary:
[3.11] gh-104010: Separate and improve docs for `typing.get_origin` and `typing.get_args` (GH-104013) (#104359)
* separate documentation and examples for both functions
* add examples demonstrating behaviour with unsupported types
* document return value of `get_origin` for `ParamSpecArgs` and `ParamSpecKwargs` instances
(cherry picked from commit a7a2dbbf72aceef61bfb50901bfa39bfb8d6d229)
Co-authored-by: chgnrdv <52372310+chgnrdv at users.noreply.github.com>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra at gmail.com>
files:
M Doc/library/typing.rst
diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index 2a53df4b746d..a99a35a7664f 100644
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -2790,24 +2790,37 @@ Introspection helpers
if a default value equal to ``None`` was set.
Now the annotation is returned unchanged.
-.. function:: get_args(tp)
.. function:: get_origin(tp)
- Provide basic introspection for generic types and special typing forms.
-
- For a typing object of the form ``X[Y, Z, ...]`` these functions return
- ``X`` and ``(Y, Z, ...)``. If ``X`` is a generic alias for a builtin or
+ Get the unsubscripted version of a type: for a typing object of the form
+ ``X[Y, Z, ...]`` return ``X``. If ``X`` is a generic alias for a builtin or
:mod:`collections` class, it gets normalized to the original class.
+ If ``X`` is an instance of :class:`ParamSpecArgs` or :class:`ParamSpecKwargs`,
+ return the underlying :class:`ParamSpec`.
+ Return ``None`` for unsupported objects.
+ Examples::
+
+ assert get_origin(str) is None
+ assert get_origin(Dict[str, int]) is dict
+ assert get_origin(Union[int, str]) is Union
+ P = ParamSpec('P')
+ assert get_origin(P.args) is P
+ assert get_origin(P.kwargs) is P
+
+ .. versionadded:: 3.8
+
+.. function:: get_args(tp)
+
+ Get type arguments with all substitutions performed: for a typing object
+ of the form ``X[Y, Z, ...]`` return ``(Y, Z, ...)``.
If ``X`` is a union or :class:`Literal` contained in another
generic type, the order of ``(Y, Z, ...)`` may be different from the order
of the original arguments ``[Y, Z, ...]`` due to type caching.
- For unsupported objects return ``None`` and ``()`` correspondingly.
+ Return ``()`` for unsupported objects.
Examples::
- assert get_origin(Dict[str, int]) is dict
+ assert get_args(int) == ()
assert get_args(Dict[int, str]) == (int, str)
-
- assert get_origin(Union[int, str]) is Union
assert get_args(Union[int, str]) == (int, str)
.. versionadded:: 3.8
More information about the Python-checkins
mailing list