From f6a2736556feae2eda5116f327872e5aede1093b Mon Sep 17 00:00:00 2001 From: Radislav Chugunov Date: Sun, 30 Apr 2023 17:43:08 +0300 Subject: [PATCH 1/5] typing: separate and improve docs for `get_origin` and `get_args` * separate documentation and examples for both functions * add examples demonstrating behaviour with unsupported types --- Doc/library/typing.rst | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 409a95d528b5d3..4927f033611c95 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -2882,24 +2882,32 @@ Introspection helpers 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 - :mod:`collections` class, it gets normalized to the original class. + 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_args(Union[int, str]) == (int, str) + + .. versionadded:: 3.8 +.. function:: get_origin(tp) + + 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. + Return ``None`` for unsupported types. + Examples:: + + assert get_origin(str) is None + assert get_origin(Dict[str, int]) is dict assert get_origin(Union[int, str]) is Union - assert get_args(Union[int, str]) == (int, str) .. versionadded:: 3.8 From 6009b6be76c709b8904b227d176f0b538977b997 Mon Sep 17 00:00:00 2001 From: Radislav Chugunov Date: Sun, 30 Apr 2023 18:07:04 +0300 Subject: [PATCH 2/5] documented return value of `get_origin` for `ParamSpecArgs` and `ParamSpecKwargs` instances --- Doc/library/typing.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 4927f033611c95..577983928862b9 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -2902,12 +2902,17 @@ Introspection helpers 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 types. 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 From e3a1b63ebfd282a0d6e9df45bfa178ed5d6323fe Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Sun, 30 Apr 2023 08:10:09 -0700 Subject: [PATCH 3/5] Update Doc/library/typing.rst --- Doc/library/typing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 577983928862b9..7c67b8e184e4e2 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -2902,8 +2902,8 @@ Introspection helpers 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``. + If ``X`` is an instance of :class:`ParamSpecArgs` or :class:`ParamSpecKwargs`, + return the underlying :class:`ParamSpec`. Return ``None`` for unsupported types. Examples:: From 83dd08293d3d1a266785a977774913c59eb0c75b Mon Sep 17 00:00:00 2001 From: Radislav Chugunov Date: Sun, 30 Apr 2023 18:10:55 +0300 Subject: [PATCH 4/5] removed doubleticks --- Doc/library/typing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 577983928862b9..7c67b8e184e4e2 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -2902,8 +2902,8 @@ Introspection helpers 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``. + If ``X`` is an instance of :class:`ParamSpecArgs` or :class:`ParamSpecKwargs`, + return the underlying :class:`ParamSpec`. Return ``None`` for unsupported types. Examples:: From d53b5952f524f8912a333a1dda92407015ba0899 Mon Sep 17 00:00:00 2001 From: Radislav Chugunov Date: Sun, 30 Apr 2023 18:26:21 +0300 Subject: [PATCH 5/5] swapped `get_args` and `get_origin` docs, changed "objects" to "types" in `get_origin` doc --- Doc/library/typing.rst | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 7c67b8e184e4e2..eb3c5a3e15c116 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -2881,22 +2881,6 @@ Introspection helpers if a default value equal to ``None`` was set. Now the annotation is returned unchanged. -.. 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. - Return ``()`` for unsupported objects. - Examples:: - - assert get_args(int) == () - assert get_args(Dict[int, str]) == (int, str) - assert get_args(Union[int, str]) == (int, str) - - .. versionadded:: 3.8 - .. function:: get_origin(tp) Get the unsubscripted version of a type: for a typing object of the form @@ -2904,7 +2888,7 @@ Introspection helpers :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 types. + Return ``None`` for unsupported objects. Examples:: assert get_origin(str) is None @@ -2916,6 +2900,22 @@ Introspection helpers .. 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. + Return ``()`` for unsupported objects. + Examples:: + + assert get_args(int) == () + assert get_args(Dict[int, str]) == (int, str) + assert get_args(Union[int, str]) == (int, str) + + .. versionadded:: 3.8 + .. function:: is_typeddict(tp) Check if a type is a :class:`TypedDict`.