From 20fa28f3fedd5e021602f07ee1678a5c5f1a7d4d Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Sat, 20 May 2023 22:45:37 -0700 Subject: [PATCH 01/13] Add documentation page for typing-extensions --- doc/Makefile | 20 ++ doc/conf.py | 29 +++ doc/index.rst | 599 ++++++++++++++++++++++++++++++++++++++++++++++++++ doc/make.bat | 35 +++ 4 files changed, 683 insertions(+) create mode 100644 doc/Makefile create mode 100644 doc/conf.py create mode 100644 doc/index.rst create mode 100644 doc/make.bat diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 00000000..d4bb2cbb --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 00000000..d5c63e01 --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,29 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'typing_extensions' +copyright = '2023, Guido van Rossum and others' +author = 'Guido van Rossum and others' +release = '4.6.0' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = ['sphinx.ext.intersphinx'] + +templates_path = ['_templates'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +intersphinx_mapping = {'py': ('https://docs.python.org/3.12', None)} + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'alabaster' +html_static_path = ['_static'] diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 00000000..defae77a --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,599 @@ + +Welcome to typing_extensions's documentation! +============================================= + +``typing_extensions`` provides common building blocks for type annotations +that are understood by static type checkers. + +The ``typing_extensions`` module serves two related purposes: + +- Enable use of new type system features on older Python versions. For example, + :py:data:`typing.TypeGuard` is new in Python 3.10, but ``typing_extensions`` allows + users on previous Python versions to use it too. +- Enable experimentation with new type system PEPs before they are accepted and + added to the :py:mod:`typing` module. + +New features may be added to ``typing_extensions`` as soon as they are specified +in a PEP that has been added to the `python/peps `_ +repository. If the PEP is accepted, the feature will then be added to :py:mod:`typing` +for the next CPython release. No typing PEP that affected ``typing_extensions`` +has been rejected so far, so we haven't yet figured out how to deal with that possibility. + +Starting with version 4.0.0, ``typing_extensions`` uses +`Semantic Versioning `_. The +major version is incremented for all backwards-incompatible changes. +Therefore, it's safe to depend +on ``typing_extensions`` like this: ``typing_extensions >=x.y, <(x+1)``, +where ``x.y`` is the first version that includes all features you need. +In view of the wide usage of ``typing_extensions`` across the ecosystem, +we are highly hesitant to break backwards compatibility, and we do not +expect to increase the major version number in the foreseeable future. + +``typing_extensions`` supports Python versions 3.7 and higher. In the future, +support for older Python versions will be dropped some time after that version +reaches end of life. + +Module contents +--------------- + +As most of the features in ``typing_extensions`` exist in :py:mod:`typing` +in newer versions of Python, the documentation here is brief and focuses +on aspects that are specific to ``typing_extensions``, such as limitations +on specific Python versions. + +Special typing primitives +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. data:: Annotated + + See :py:data:`typing.Annotated`. In ``typing`` since 3.9. + + .. versionchanged:: 4.1.0 + + ``Annotated`` can now wrap :data:`ClassVar` and :data:`Final`. + +.. data:: Any + + See :py:data:`typing.Any`. + + Since Python 3.11, ``typing.Any`` can be used as a base class. + ``typing_extensions.Any`` supports this feature on older versions. + + .. versionadded:: 4.4.0 + + Added to support inheritance from ``Any``. + +.. data:: ClassVar + + See :py:data:`typing.ClassVar`. In ``typing`` since 3.5.3. + +.. data:: Concatenate + + See :py:data:`typing.Concatenate`. In ``typing`` since 3.10. + +.. data:: Final + + See :py:data:`typing.Final`. In ``typing`` since 3.8. + +.. data:: Literal + + See :py:data:`typing.Literal`. In ``typing`` since 3.8. + + :py:data:`typing.Literal` does not flatten or deduplicate parameters on Python <3.9.1, and a + caching bug was fixed in 3.10.1/3.9.8. The ``typing_extensions`` version + flattens and deduplicates parameters on all Python versions, and the caching + bug is also fixed on all versions. + + .. versionchanged:: 4.6.0 + + Backported the bug fixes from :py:gh:`29334`, :py:gh:`23294`, and :py:gh:`23383`. + +.. data:: LiteralString + + See :py:data:`typing.LiteralString`. In ``typing`` since 3.11. + + .. versionadded:: 4.1.0 + +.. class:: NamedTuple + + See :py:class:`typing.NamedTuple`. + + ``typing_extensions`` backports several changes + to ``NamedTuple`` on Python 3.11 and lower: in 3.11, + support for generic ``NamedTuple`` was added, and + in 3.12, the ``__orig_bases__`` attribute was added. + + .. versionadded:: 4.3.0 + + Added to provide support for generic ``NamedTuple``. + + .. versionchanged:: 4.6.0 + + Support for the ``__orig_bases__`` attribute was added. + +.. data:: Never + + See :py:data:`typing.Never`. In ``typing`` since 3.11. + + .. versionadded:: 4.1.0 + +.. class:: NewType(name, tp) + + See :py:class:`typing.NewType`. In ``typing`` since 3.5.2. + + ``NewType`` was made picklable in 3.10 and an error message was + improved in 3.11; ``typing_extensions`` backports these changes. + + .. versionchanged:: 4.6.0 + + The improvements from Python 3.10 and 3.11 were backported. + +.. data:: NoReturn + + See :py:data:`typing.NoReturn`. In ``typing`` since 3.5.4 and 3.6.2. + +.. data:: NotRequired + + See :py:data:`typing.NotRequired`. In ``typing`` since 3.11. + + .. versionadded:: 4.0.0 + +.. class:: ParamSpec(name, *, default=...) + + See :py:class:`typing.ParamSpec`. In ``typing`` since 3.10. + + The ``typing_extensions`` version adds support for the + ``default=`` argument from :pep:`696`. + + .. versionchanged:: 4.4.0 + + Added support for the ``default=`` argument. + + .. versionchanged:: 4.6.0 + + The implementation was changed for compatibility with Python 3.12. + +.. class:: ParamSpecArgs + +.. class:: ParamSpecKwargs + + See :py:class:`typing.ParamSpecArgs` and :py:class:`typing.ParamSpecKwargs`. + In ``typing`` since 3.10. + +.. class:: Protocol + + See :py:class:`typing.Protocol`. In ``typing`` since 3.8. + + Python 3.12 improves the performance of runtime-checkable protocols; + ``typing_extensions`` backports this improvement. + + .. versionchanged:: 4.6.0 + + Backported the ability to define ``__init__`` methods on Protocol classes. + + .. versionchanged:: 4.6.0 + + Backported changes to runtime-checkable protocols from Python 3.12. + +.. data:: Required + + See :py:data:`typing.Required`. In ``typing`` since 3.11. + + .. versionadded:: 4.0.0 + +.. data:: Self + + See :py:data:`typing.Self`. In ``typing`` since 3.11. + + .. versionadded:: 4.0.0 + +.. class:: Type + + See :py:class:`typing.Type`. In ``typing`` since 3.5.2. + +.. data:: TypeAlias + + See :py:data:`typing.TypeAlias`. In ``typing`` since 3.10. + +.. class:: TypeAliasType(name, value, *, type_params=()) + + See :py:class:`typing.TypeAliasType`. In ``typing`` since 3.12. + + .. versionadded:: 4.6.0 + +.. data:: TypeGuard + + See :py:data:`typing.TypeGuard`. In ``typing`` since 3.10. + +.. class:: TypedDict + + See :py:class:`typing.TypedDict`. In ``typing`` since 3.8. + + ``typing_extensions`` backports various bug fixes and improvements + to ``TypedDict`` on Python 3.11 and lower. + :py:class:`TypedDict` does not store runtime information + about which (if any) keys are non-required in Python 3.8, and does not + honor the ``total`` keyword with old-style ``TypedDict()`` in Python + 3.9.0 and 3.9.1. :py:class:`typing.TypedDict` also does not support multiple inheritance + with :py:class:`typing.Generic` on Python <3.11, and :py:class:`typing.TypedDict` classes do not + consistently have the ``__orig_bases__`` attribute on Python <3.12. The + ``typing_extensions`` backport provides all of these features and bugfixes on + all Python versions. + + .. versionadded:: 4.3.0 + + Added to provide support for generic ``TypedDict``. + + .. versionchanged:: 4.6.0 + + A :py:exc:`DeprecationWarning` is now emitted when a call-based + ``TypedDict`` is constructed using keyword arguments. + + .. versionchanged:: 4.6.0 + + Support for the ``__orig_bases__`` attribute was added. + +.. class:: TypeVar(name, *constraints, bound=None, covariant=False, + contravariant=False, infer_variance=False, default=...) + + See :py:class:`typing.TypeVar`. + + The ``typing_extensions`` version adds support for the + ``default=`` argument from :pep:`696`, as well as the + ``infer_variance=`` argument from :pep:`695` (also available + in Python 3.12). + + .. versionadded:: 4.4.0 + + Added in order to support the new ``default=`` and + ``infer_variance=`` arguments. + + .. versionchanged:: 4.6.0 + + The implementation was changed for compatibility with Python 3.12. + +.. class:: TypeVarTuple(name, *, default=...) + + See :py:class:`typing.TypeVarTuple`. In ``typing`` since 3.10. + + The ``typing_extensions`` version adds support for the + ``default=`` argument from :pep:`696`. + + .. versionadded:: 4.1.0 + + .. versionchanged:: 4.4.0 + + Added support for the ``default=`` argument. + + .. versionchanged:: 4.6.0 + + The implementation was changed for compatibility with Python 3.12. + +.. data:: Unpack + + See :py:data:`typing.Unpack`. In ``typing`` since 3.10. + + In Python 3.12, the ``repr()`` was changed as a result of :pep:`692`. + ``typing_extensions`` backports this change. + + .. versionadded:: 4.1.0 + + .. versionchanged:: 4.6.0 + + Backport ``repr()`` changes from Python 3.12. + +Generic concrete collections +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. class:: ChainMap + + See :py:class:`typing.ChainMap`. In ``typing`` since 3.5.4 and 3.6.1. + +.. class:: Counter + + See :py:class:`typing.Counter`. In ``typing`` since 3.5.4 and 3.6.1. + +.. class:: DefaultDict + + See :py:class:`typing.DefaultDict`. In ``typing`` since 3.5.2. + +.. class:: Deque + + See :py:class:`typing.Deque`. In ``typing`` since 3.5.4 and 3.6.1. + +.. class:: OrderedDict + + See :py:class:`typing.OrderedDict`. In ``typing`` since 3.7.2. + +Abstract Base Classes +~~~~~~~~~~~~~~~~~~~~~ + +.. class:: AsyncContextManager + + See :py:class:`typing.AsyncContextManager`. In ``typing`` since 3.5.4 and 3.6.2. + +.. class:: AsyncGenerator + + See :py:class:`typing.AsyncGenerator`. In ``typing`` since 3.6.1. + +.. class:: AsyncIterable + + See :py:class:`typing.AsyncIterable`. In ``typing`` since 3.5.2. + +.. class:: AsyncIterator + + See :py:class:`typing.AsyncIterator`. In ``typing`` since 3.5.2. + +.. class:: Awaitable + + See :py:class:`typing.Awaitable`. In ``typing`` since 3.5.2. + +.. class:: Buffer + + See :py:class:`collections.abc.Buffer`. Added to the standard library + in Python 3.12. + + .. versionadded:: 4.6.0 + +.. class:: ContextManager + + See :py:class:`typing.ContextManager`. In ``typing`` since 3.5.4. + +.. class:: Coroutine + + See :py:class:`typing.Coroutine`. In ``typing`` since 3.5.3. + +Protocols +~~~~~~~~~ + +.. class:: SupportsAbs + + See :py:class:`typing.SupportsAbs`. + + ``typing_extensions`` backports a more performant version of this + protocol in Python 3.11 and lower. + + .. versionadded:: 4.6.0 + +.. class:: SupportsBytes + + See :py:class:`typing.SupportsBytes`. + + ``typing_extensions`` backports a more performant version of this + protocol in Python 3.11 and lower. + + .. versionadded:: 4.6.0 + +.. class:: SupportsComplex + + See :py:class:`typing.SupportsComplex`. + + ``typing_extensions`` backports a more performant version of this + protocol in Python 3.11 and lower. + + .. versionadded:: 4.6.0 + +.. class:: SupportsFloat + + See :py:class:`typing.SupportsFloat`. + + ``typing_extensions`` backports a more performant version of this + protocol in Python 3.11 and lower. + + .. versionadded:: 4.6.0 + +.. class:: SupportsIndex + + See :py:class:`typing.SupportsIndex`. In ``typing`` since 3.8. + + ``typing_extensions`` backports a more performant version of this + protocol in Python 3.11 and lower. + + .. versionchanged:: 4.6.0 + + Backported the performance improvements from Python 3.12. + +.. class:: SupportsInt + + See :py:class:`typing.SupportsInt`. + + ``typing_extensions`` backports a more performant version of this + protocol in Python 3.11 and lower. + + .. versionadded:: 4.6.0 + +.. class:: SupportsRound + + See :py:class:`typing.SupportsRound`. + + ``typing_extensions`` backports a more performant version of this + protocol in Python 3.11 and lower. + + .. versionadded:: 4.6.0 + +Decorators +~~~~~~~~~~ + +.. decorator:: dataclass_transform(*, eq_default=False, order_default=False, + kw_only_default=False, frozen_default=False, + field_specifiers=(), **kwargs) + + See :py:func:`typing.dataclass_transform`. In ``typing`` since 3.11. + + Python 3.12 adds the ``frozen_default`` parameter; ``typing_extensions`` + backports this parameter. + + .. versionadded:: 4.1.0 + + .. versionchanged:: 4.2.0 + + The ``field_descriptors`` parameter was renamed to ``field_specifiers``. + For compatibility, the decorator now accepts arbitrary keyword arguments. + + .. versionchanged:: 4.5.0 + + The ``frozen_default`` parameter was added. + +.. decorator:: deprecated(msg, *, category=DeprecationWarning, stacklevel=1) + + See :pep:`702`. + + .. versionadded:: 4.5.0 + +.. decorator:: final + + See :py:func:`typing.final`. In ``typing`` since 3.8. + + Since Python 3.11, this decorator supports runtime introspection + through the ``__final__`` attribute; ``typing_extensions.final`` + backports this feature. + + .. versionchanged:: 4.1.0 + + The ``__final__`` attribute is now set on decorated objects. + +.. decorator:: overload + + See :py:func:`typing.overload`. + + Since Python 3.11, this decorator supports runtime introspection + through :func:`get_overloads`; ``typing_extensions.overload`` + backports this feature. + + .. versionchanged:: 4.2.0 + + Added to provide support for introspection through :func:`get_overloads` was added. + +.. decorator:: override + + See :py:func:`typing.override`. In ``typing`` since 3.12. + + .. versionadded:: 4.4.0 + + .. versionchanged:: 4.5.0 + + The decorator now sets the ``__override__`` attribute on the decorated + object. + +.. decorator:: runtime_checkable + + See :py:func:`typing.runtime_checkable`. In ``typing`` since 3.8. + + In Python 3.12, the performance of runtime-checkable protocols was + improved, and ``typing_extensions`` backports these performance + improvements. + +Functions +~~~~~~~~~ + +.. function:: assert_never(arg) + + See :py:func:`typing.assert_never`. In ``typing`` since 3.11. + + .. versionadded:: 4.1.0 + +.. function:: assert_type(val, typ) + + See :py:func:`typing.assert_type`. In ``typing`` since 3.11. + + .. versionadded:: 4.2.0 + +.. function:: clear_overloads() + + See :py:func:`typing.clear_overloads`. In ``typing`` since 3.11. + + .. versionadded:: 4.2.0 + +.. function:: get_args(tp) + + See :py:func:`typing.get_args`. In ``typing`` since 3.8. + + This function was changed in 3.9 and 3.10 to deal with :data:`Annotated` + and :class:`ParamSpec` correctly; ``typing_extensions`` backports these + fixes. + +.. function:: get_origin(tp) + + See :py:func:`typing.get_origin`. In ``typing`` since 3.8. + + This function was changed in 3.9 and 3.10 to deal with :data:`Annotated` + and :class:`ParamSpec` correctly; ``typing_extensions`` backports these + fixes. + +.. function:: get_original_bases(cls) + + See :py:func:`types.get_original_bases`. Added to the standard library + in Python 3.12. + + This function should always produce correct results when called on classes + constructed using features from ``typing_extensions``. However, it may + produce incorrect results when called on some :py:class:`NamedTuple` or + :py:class:`TypedDict` on Python <=3.11. + + .. versionadded:: 4.6.0 + +.. function:: get_overloads(func) + + See :py:func:`typing.get_overloads`. In ``typing`` since 3.11. + + Before Python 3.11, this works only with overloads created through + :func:`overload`, not with :py:func:`typing.overload`. + + .. versionadded:: 4.2.0 + +.. function:: get_type_hints(obj, globalns=None, localns=None, include_extras=False) + + See :py:func:`typing.get_type_hints`. + + In Python 3.11, this function was changed to support the new + :py:data:`typing.Required`. ``typing_extensions`` backports these + fixes. + + .. versionchanged:: 4.1.0 + + Interaction with :data:`Required` and :data:`NotRequired`. + +.. function:: is_typeddict(tp) + + See :py:func:`typing.is_typeddict`. In ``typing`` since 3.10. + + On versions where :class:`TypedDict` is not the same as + :py:class:`typing.TypedDict`, this function recognizes + ``TypedDict`` classes created through either. + + .. versionadded:: 4.1.0 + +.. function:: reveal_type(obj) + + See :py:func:`typing.reveal_type`. In ``typing`` since 3.11. + + .. versionadded:: 4.1.0 + +Other +~~~~~ + +.. class:: Text + + See :py:class:`typing.Text`. In ``typing`` since 3.5.2. + +.. data:: TYPE_CHECKING + + See :py:data:`typing.TYPE_CHECKING`. In ``typing`` since 3.5.2. + +Limitations +----------- + +There are a few types whose interface was modified between different +versions of typing. For example, :py:class:`typing.Sequence` was modified to +subclass :py:class:`typing.Reversible` as of Python 3.5.3. + +These changes are *not* backported to prevent subtle compatibility +issues when mixing the differing implementations of modified classes. + +Certain types have incorrect runtime behavior due to limitations of older +versions of the typing module: + +- :class:`ParamSpec` and :data:`Concatenate` will not work with :func:`get_args` and + :func:`get_origin`. +- Certain :pep:`612` special cases in user-defined + :py:class:`typing.Generic`\ s are also not available. diff --git a/doc/make.bat b/doc/make.bat new file mode 100644 index 00000000..32bb2452 --- /dev/null +++ b/doc/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd From d6eb8138312874b4cb3e31f8364cce5a87de7e03 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Sun, 21 May 2023 05:50:24 -0700 Subject: [PATCH 02/13] Apply suggestions from code review Co-authored-by: Alex Waygood --- doc/index.rst | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/doc/index.rst b/doc/index.rst index defae77a..e0b11b1d 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -100,12 +100,12 @@ Special typing primitives ``typing_extensions`` backports several changes to ``NamedTuple`` on Python 3.11 and lower: in 3.11, - support for generic ``NamedTuple`` was added, and + support for generic ``NamedTuple``\ s was added, and in 3.12, the ``__orig_bases__`` attribute was added. .. versionadded:: 4.3.0 - Added to provide support for generic ``NamedTuple``. + Added to provide support for generic ``NamedTuple``\ s. .. versionchanged:: 4.6.0 @@ -121,7 +121,7 @@ Special typing primitives See :py:class:`typing.NewType`. In ``typing`` since 3.5.2. - ``NewType`` was made picklable in 3.10 and an error message was + Instances of ``NewType`` were made picklable in 3.10 and an error message was improved in 3.11; ``typing_extensions`` backports these changes. .. versionchanged:: 4.6.0 @@ -173,7 +173,8 @@ Special typing primitives .. versionchanged:: 4.6.0 - Backported changes to runtime-checkable protocols from Python 3.12. + Backported changes to runtime-checkable protocols from Python 3.12, + including :py:gh:`103034` and :py:gh:`26067`. .. data:: Required @@ -222,7 +223,7 @@ Special typing primitives .. versionadded:: 4.3.0 - Added to provide support for generic ``TypedDict``. + Added support for generic ``TypedDict``\ s. .. versionchanged:: 4.6.0 @@ -254,7 +255,7 @@ Special typing primitives .. class:: TypeVarTuple(name, *, default=...) - See :py:class:`typing.TypeVarTuple`. In ``typing`` since 3.10. + See :py:class:`typing.TypeVarTuple`. In ``typing`` since 3.11. The ``typing_extensions`` version adds support for the ``default=`` argument from :pep:`696`. @@ -271,7 +272,7 @@ Special typing primitives .. data:: Unpack - See :py:data:`typing.Unpack`. In ``typing`` since 3.10. + See :py:data:`typing.Unpack`. In ``typing`` since 3.11. In Python 3.12, the ``repr()`` was changed as a result of :pep:`692`. ``typing_extensions`` backports this change. @@ -351,7 +352,7 @@ Protocols See :py:class:`typing.SupportsAbs`. ``typing_extensions`` backports a more performant version of this - protocol in Python 3.11 and lower. + protocol on Python 3.11 and lower. .. versionadded:: 4.6.0 @@ -436,7 +437,7 @@ Decorators .. decorator:: deprecated(msg, *, category=DeprecationWarning, stacklevel=1) - See :pep:`702`. + See :pep:`702`. Experimental; not yet part of the standard library. .. versionadded:: 4.5.0 @@ -445,12 +446,12 @@ Decorators See :py:func:`typing.final`. In ``typing`` since 3.8. Since Python 3.11, this decorator supports runtime introspection - through the ``__final__`` attribute; ``typing_extensions.final`` + by setting the ``__final__`` attribute wherever possible; ``typing_extensions.final`` backports this feature. .. versionchanged:: 4.1.0 - The ``__final__`` attribute is now set on decorated objects. + The decorator now attempts to set the ``__final__`` attribute on decorated objects. .. decorator:: overload @@ -472,7 +473,7 @@ Decorators .. versionchanged:: 4.5.0 - The decorator now sets the ``__override__`` attribute on the decorated + The decorator now attempts to set the ``__override__`` attribute on the decorated object. .. decorator:: runtime_checkable @@ -528,7 +529,7 @@ Functions This function should always produce correct results when called on classes constructed using features from ``typing_extensions``. However, it may produce incorrect results when called on some :py:class:`NamedTuple` or - :py:class:`TypedDict` on Python <=3.11. + :py:class:`TypedDict` classes on Python <=3.11. .. versionadded:: 4.6.0 @@ -559,7 +560,7 @@ Functions On versions where :class:`TypedDict` is not the same as :py:class:`typing.TypedDict`, this function recognizes - ``TypedDict`` classes created through either. + ``TypedDict`` classes created through either mechanism. .. versionadded:: 4.1.0 From e0acf93350538e7f122991d560956e2a061ad711 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Sun, 21 May 2023 05:51:35 -0700 Subject: [PATCH 03/13] More in -> on --- doc/index.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/index.rst b/doc/index.rst index e0b11b1d..aa67a21c 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -361,7 +361,7 @@ Protocols See :py:class:`typing.SupportsBytes`. ``typing_extensions`` backports a more performant version of this - protocol in Python 3.11 and lower. + protocol on Python 3.11 and lower. .. versionadded:: 4.6.0 @@ -370,7 +370,7 @@ Protocols See :py:class:`typing.SupportsComplex`. ``typing_extensions`` backports a more performant version of this - protocol in Python 3.11 and lower. + protocol on Python 3.11 and lower. .. versionadded:: 4.6.0 @@ -379,7 +379,7 @@ Protocols See :py:class:`typing.SupportsFloat`. ``typing_extensions`` backports a more performant version of this - protocol in Python 3.11 and lower. + protocol on Python 3.11 and lower. .. versionadded:: 4.6.0 @@ -388,7 +388,7 @@ Protocols See :py:class:`typing.SupportsIndex`. In ``typing`` since 3.8. ``typing_extensions`` backports a more performant version of this - protocol in Python 3.11 and lower. + protocol on Python 3.11 and lower. .. versionchanged:: 4.6.0 @@ -399,7 +399,7 @@ Protocols See :py:class:`typing.SupportsInt`. ``typing_extensions`` backports a more performant version of this - protocol in Python 3.11 and lower. + protocol on Python 3.11 and lower. .. versionadded:: 4.6.0 @@ -408,7 +408,7 @@ Protocols See :py:class:`typing.SupportsRound`. ``typing_extensions`` backports a more performant version of this - protocol in Python 3.11 and lower. + protocol on Python 3.11 and lower. .. versionadded:: 4.6.0 @@ -451,7 +451,7 @@ Decorators .. versionchanged:: 4.1.0 - The decorator now attempts to set the ``__final__`` attribute on decorated objects. + The decorator now attempts to set the ``__final__`` attribute on decorated objects. .. decorator:: overload From 969853db234fe0b0154e546d1caa43ce3baf8fcd Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Sun, 21 May 2023 05:52:59 -0700 Subject: [PATCH 04/13] changed, not added --- doc/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/index.rst b/doc/index.rst index aa67a21c..4b5e1d54 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -221,7 +221,7 @@ Special typing primitives ``typing_extensions`` backport provides all of these features and bugfixes on all Python versions. - .. versionadded:: 4.3.0 + .. versionchanged:: 4.3.0 Added support for generic ``TypedDict``\ s. From 420249217366a41a72331216a4a2fbaee43308d1 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Sun, 21 May 2023 13:49:22 -0700 Subject: [PATCH 05/13] Apply suggestions from code review Co-authored-by: Alex Waygood --- doc/index.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/doc/index.rst b/doc/index.rst index 4b5e1d54..a06fd8d2 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -2,10 +2,9 @@ Welcome to typing_extensions's documentation! ============================================= -``typing_extensions`` provides common building blocks for type annotations -that are understood by static type checkers. - -The ``typing_extensions`` module serves two related purposes: +``typing_extensions`` complements the standard-library :py:mod:`typing` module, +providing runtime support for type hints as specified by :pep:`484` and subsequent +PEPs. The module serves two related purposes: - Enable use of new type system features on older Python versions. For example, :py:data:`typing.TypeGuard` is new in Python 3.10, but ``typing_extensions`` allows @@ -15,9 +14,10 @@ The ``typing_extensions`` module serves two related purposes: New features may be added to ``typing_extensions`` as soon as they are specified in a PEP that has been added to the `python/peps `_ -repository. If the PEP is accepted, the feature will then be added to :py:mod:`typing` -for the next CPython release. No typing PEP that affected ``typing_extensions`` -has been rejected so far, so we haven't yet figured out how to deal with that possibility. +repository. If the PEP is accepted, the feature will then be added to the +:py:mod:`typing` module for the next CPython release. No typing PEP that +affected ``typing_extensions`` has been rejected so far, so we haven't yet +figured out how to deal with that possibility. Starting with version 4.0.0, ``typing_extensions`` uses `Semantic Versioning `_. The @@ -461,7 +461,7 @@ Decorators through :func:`get_overloads`; ``typing_extensions.overload`` backports this feature. - .. versionchanged:: 4.2.0 + .. versionadded:: 4.2.0 Added to provide support for introspection through :func:`get_overloads` was added. @@ -547,8 +547,8 @@ Functions See :py:func:`typing.get_type_hints`. In Python 3.11, this function was changed to support the new - :py:data:`typing.Required`. ``typing_extensions`` backports these - fixes. + :py:data:`typing.Required` and :py:data:`typing.NotRequired`. + ``typing_extensions`` backports these fixes. .. versionchanged:: 4.1.0 @@ -584,7 +584,7 @@ Other Limitations ----------- -There are a few types whose interface was modified between different +There are a few types where the interface was modified between different versions of typing. For example, :py:class:`typing.Sequence` was modified to subclass :py:class:`typing.Reversible` as of Python 3.5.3. From 7e61686278832ea7420c40ff0d942ed00fe62abd Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Sun, 21 May 2023 13:51:16 -0700 Subject: [PATCH 06/13] Update doc/index.rst Co-authored-by: Alex Waygood --- doc/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/index.rst b/doc/index.rst index a06fd8d2..2493fae3 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -463,7 +463,7 @@ Decorators .. versionadded:: 4.2.0 - Added to provide support for introspection through :func:`get_overloads` was added. + Introspection support via :func:`get_overloads` was added. .. decorator:: override From 4c29bceb2207e7784b4f56fb2d95731524afe1e6 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Sun, 21 May 2023 13:51:46 -0700 Subject: [PATCH 07/13] changed not added --- doc/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/index.rst b/doc/index.rst index 2493fae3..b60a3040 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -461,7 +461,7 @@ Decorators through :func:`get_overloads`; ``typing_extensions.overload`` backports this feature. - .. versionadded:: 4.2.0 + .. versionchanged:: 4.2.0 Introspection support via :func:`get_overloads` was added. From 722ac0b747f8b4c0d719da3b39651f8765df8413 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Sun, 21 May 2023 13:52:11 -0700 Subject: [PATCH 08/13] Update doc/index.rst --- doc/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/index.rst b/doc/index.rst index b60a3040..8e91a57e 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -9,7 +9,7 @@ PEPs. The module serves two related purposes: - Enable use of new type system features on older Python versions. For example, :py:data:`typing.TypeGuard` is new in Python 3.10, but ``typing_extensions`` allows users on previous Python versions to use it too. -- Enable experimentation with new type system PEPs before they are accepted and +- Enable experimentation with type system features proposed in new PEPs before they are accepted and added to the :py:mod:`typing` module. New features may be added to ``typing_extensions`` as soon as they are specified From 3d903ad26a23b2420b13723c7b15c1847c22d1a5 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Sun, 21 May 2023 15:13:26 -0700 Subject: [PATCH 09/13] Remove limitations section - The stuff about Reversible is no longer relevant - Can't confirm issues with Concatenate - Add note specifically to ParamSpec docs --- doc/index.rst | 23 +++++------------------ 1 file changed, 5 insertions(+), 18 deletions(-) diff --git a/doc/index.rst b/doc/index.rst index 8e91a57e..4bb9ce3e 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -145,6 +145,11 @@ Special typing primitives The ``typing_extensions`` version adds support for the ``default=`` argument from :pep:`696`. + On older Python versions, ``typing_extensions.ParamSpec`` may not work + correctly with introspection tools like :func:`get_args` and + :func:`get_origin`. Certain special cases in user-defined + :py:class:`typing.Generic`\ s are also not available. + .. versionchanged:: 4.4.0 Added support for the ``default=`` argument. @@ -580,21 +585,3 @@ Other .. data:: TYPE_CHECKING See :py:data:`typing.TYPE_CHECKING`. In ``typing`` since 3.5.2. - -Limitations ------------ - -There are a few types where the interface was modified between different -versions of typing. For example, :py:class:`typing.Sequence` was modified to -subclass :py:class:`typing.Reversible` as of Python 3.5.3. - -These changes are *not* backported to prevent subtle compatibility -issues when mixing the differing implementations of modified classes. - -Certain types have incorrect runtime behavior due to limitations of older -versions of the typing module: - -- :class:`ParamSpec` and :data:`Concatenate` will not work with :func:`get_args` and - :func:`get_origin`. -- Certain :pep:`612` special cases in user-defined - :py:class:`typing.Generic`\ s are also not available. From 90567fff249e8688bd48b4b9c34947225bcb4aad Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Sun, 21 May 2023 15:17:48 -0700 Subject: [PATCH 10/13] PEP links --- doc/index.rst | 40 ++++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/doc/index.rst b/doc/index.rst index 4bb9ce3e..c518b9e4 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -46,7 +46,7 @@ Special typing primitives .. data:: Annotated - See :py:data:`typing.Annotated`. In ``typing`` since 3.9. + See :py:data:`typing.Annotated` and :pep:`593`. In ``typing`` since 3.9. .. versionchanged:: 4.1.0 @@ -65,19 +65,19 @@ Special typing primitives .. data:: ClassVar - See :py:data:`typing.ClassVar`. In ``typing`` since 3.5.3. + See :py:data:`typing.ClassVar` and :pep:`526`. In ``typing`` since 3.5.3. .. data:: Concatenate - See :py:data:`typing.Concatenate`. In ``typing`` since 3.10. + See :py:data:`typing.Concatenate` and :pep:`612`. In ``typing`` since 3.10. .. data:: Final - See :py:data:`typing.Final`. In ``typing`` since 3.8. + See :py:data:`typing.Final` and :pep:`591`. In ``typing`` since 3.8. .. data:: Literal - See :py:data:`typing.Literal`. In ``typing`` since 3.8. + See :py:data:`typing.Literal` and :pep:`586`. In ``typing`` since 3.8. :py:data:`typing.Literal` does not flatten or deduplicate parameters on Python <3.9.1, and a caching bug was fixed in 3.10.1/3.9.8. The ``typing_extensions`` version @@ -90,7 +90,7 @@ Special typing primitives .. data:: LiteralString - See :py:data:`typing.LiteralString`. In ``typing`` since 3.11. + See :py:data:`typing.LiteralString` and :pep:`675`. In ``typing`` since 3.11. .. versionadded:: 4.1.0 @@ -134,13 +134,13 @@ Special typing primitives .. data:: NotRequired - See :py:data:`typing.NotRequired`. In ``typing`` since 3.11. + See :py:data:`typing.NotRequired` and :pep:`655`. In ``typing`` since 3.11. .. versionadded:: 4.0.0 .. class:: ParamSpec(name, *, default=...) - See :py:class:`typing.ParamSpec`. In ``typing`` since 3.10. + See :py:class:`typing.ParamSpec` and :pep:`612`. In ``typing`` since 3.10. The ``typing_extensions`` version adds support for the ``default=`` argument from :pep:`696`. @@ -167,7 +167,7 @@ Special typing primitives .. class:: Protocol - See :py:class:`typing.Protocol`. In ``typing`` since 3.8. + See :py:class:`typing.Protocol` and :pep:`544`. In ``typing`` since 3.8. Python 3.12 improves the performance of runtime-checkable protocols; ``typing_extensions`` backports this improvement. @@ -183,13 +183,13 @@ Special typing primitives .. data:: Required - See :py:data:`typing.Required`. In ``typing`` since 3.11. + See :py:data:`typing.Required` and :pep:`655`. In ``typing`` since 3.11. .. versionadded:: 4.0.0 .. data:: Self - See :py:data:`typing.Self`. In ``typing`` since 3.11. + See :py:data:`typing.Self` and :pep:`673`. In ``typing`` since 3.11. .. versionadded:: 4.0.0 @@ -199,21 +199,21 @@ Special typing primitives .. data:: TypeAlias - See :py:data:`typing.TypeAlias`. In ``typing`` since 3.10. + See :py:data:`typing.TypeAlias` and :pep:`613`. In ``typing`` since 3.10. .. class:: TypeAliasType(name, value, *, type_params=()) - See :py:class:`typing.TypeAliasType`. In ``typing`` since 3.12. + See :py:class:`typing.TypeAliasType` and :pep:`695`. In ``typing`` since 3.12. .. versionadded:: 4.6.0 .. data:: TypeGuard - See :py:data:`typing.TypeGuard`. In ``typing`` since 3.10. + See :py:data:`typing.TypeGuard` and :pep:`647`. In ``typing`` since 3.10. .. class:: TypedDict - See :py:class:`typing.TypedDict`. In ``typing`` since 3.8. + See :py:class:`typing.TypedDict` and :pep:`589`. In ``typing`` since 3.8. ``typing_extensions`` backports various bug fixes and improvements to ``TypedDict`` on Python 3.11 and lower. @@ -260,7 +260,7 @@ Special typing primitives .. class:: TypeVarTuple(name, *, default=...) - See :py:class:`typing.TypeVarTuple`. In ``typing`` since 3.11. + See :py:class:`typing.TypeVarTuple` and :pep:`646`. In ``typing`` since 3.11. The ``typing_extensions`` version adds support for the ``default=`` argument from :pep:`696`. @@ -277,7 +277,7 @@ Special typing primitives .. data:: Unpack - See :py:data:`typing.Unpack`. In ``typing`` since 3.11. + See :py:data:`typing.Unpack` and :pep:`646`. In ``typing`` since 3.11. In Python 3.12, the ``repr()`` was changed as a result of :pep:`692`. ``typing_extensions`` backports this change. @@ -424,7 +424,7 @@ Decorators kw_only_default=False, frozen_default=False, field_specifiers=(), **kwargs) - See :py:func:`typing.dataclass_transform`. In ``typing`` since 3.11. + See :py:func:`typing.dataclass_transform` and :pep:`681`. In ``typing`` since 3.11. Python 3.12 adds the ``frozen_default`` parameter; ``typing_extensions`` backports this parameter. @@ -448,7 +448,7 @@ Decorators .. decorator:: final - See :py:func:`typing.final`. In ``typing`` since 3.8. + See :py:func:`typing.final` and :pep:`591`. In ``typing`` since 3.8. Since Python 3.11, this decorator supports runtime introspection by setting the ``__final__`` attribute wherever possible; ``typing_extensions.final`` @@ -472,7 +472,7 @@ Decorators .. decorator:: override - See :py:func:`typing.override`. In ``typing`` since 3.12. + See :py:func:`typing.override` and :pep:`698`. In ``typing`` since 3.12. .. versionadded:: 4.4.0 From 30291127fbcdbaa6491c4418f42fc0e6ca8c44ec Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Sun, 21 May 2023 15:37:42 -0700 Subject: [PATCH 11/13] Custom extension for GH links --- doc/.gitignore | 1 + doc/_extensions/__init__.py | 0 doc/_extensions/gh_link.py | 14 ++++++++++++++ doc/conf.py | 7 ++++++- doc/index.rst | 7 +++++-- 5 files changed, 26 insertions(+), 3 deletions(-) create mode 100644 doc/.gitignore create mode 100644 doc/_extensions/__init__.py create mode 100644 doc/_extensions/gh_link.py diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 00000000..69fa449d --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1 @@ +_build/ diff --git a/doc/_extensions/__init__.py b/doc/_extensions/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/doc/_extensions/gh_link.py b/doc/_extensions/gh_link.py new file mode 100644 index 00000000..e1a2e3ef --- /dev/null +++ b/doc/_extensions/gh_link.py @@ -0,0 +1,14 @@ +from docutils import nodes + +def setup(app): + app.add_role('pr', autolink('https://github.com/python/typing_extensions/pull/{}', 'PR #')) + app.add_role('pr-cpy', autolink('https://github.com/python/cpython/pull/{}', 'CPython PR #')) + app.add_role('issue', autolink('https://github.com/python/typing_extensions/issues/{}', 'issue #')) + app.add_role('issue-cpy', autolink('https://github.com/python/cpython/issues/{}', "CPython issue #")) + +def autolink(pattern: str, prefix: str): + def role(name, rawtext, text: str, lineno, inliner, options={}, content=[]): + url = pattern.format(text) + node = nodes.reference(rawtext, f"{prefix}{text}", refuri=url, **options) + return [node], [] + return role diff --git a/doc/conf.py b/doc/conf.py index d5c63e01..7984bc22 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -3,6 +3,11 @@ # For the full list of built-in configuration values, see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html +import os.path +import sys + +sys.path.insert(0, os.path.abspath('.')) + # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information @@ -14,7 +19,7 @@ # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -extensions = ['sphinx.ext.intersphinx'] +extensions = ['sphinx.ext.intersphinx', '_extensions.gh_link'] templates_path = ['_templates'] exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] diff --git a/doc/index.rst b/doc/index.rst index c518b9e4..4334414a 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -71,6 +71,9 @@ Special typing primitives See :py:data:`typing.Concatenate` and :pep:`612`. In ``typing`` since 3.10. + The backport does not support certain operations involving ``...`` as + a parameter; see :issue:`48` and :issue:`110` for details. + .. data:: Final See :py:data:`typing.Final` and :pep:`591`. In ``typing`` since 3.8. @@ -86,7 +89,7 @@ Special typing primitives .. versionchanged:: 4.6.0 - Backported the bug fixes from :py:gh:`29334`, :py:gh:`23294`, and :py:gh:`23383`. + Backported the bug fixes from :pr-cpy:`29334`, :pr-cpy:`23294`, and :pr-cpy:`23383`. .. data:: LiteralString @@ -179,7 +182,7 @@ Special typing primitives .. versionchanged:: 4.6.0 Backported changes to runtime-checkable protocols from Python 3.12, - including :py:gh:`103034` and :py:gh:`26067`. + including :pr-cpy:`103034` and :pr-cpy:`26067`. .. data:: Required From c5fa9809fd09c094cd2802a3783abecb4d8a2cc4 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Sun, 21 May 2023 15:38:58 -0700 Subject: [PATCH 12/13] black --- doc/_extensions/gh_link.py | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/doc/_extensions/gh_link.py b/doc/_extensions/gh_link.py index e1a2e3ef..35968a83 100644 --- a/doc/_extensions/gh_link.py +++ b/doc/_extensions/gh_link.py @@ -1,14 +1,27 @@ from docutils import nodes + def setup(app): - app.add_role('pr', autolink('https://github.com/python/typing_extensions/pull/{}', 'PR #')) - app.add_role('pr-cpy', autolink('https://github.com/python/cpython/pull/{}', 'CPython PR #')) - app.add_role('issue', autolink('https://github.com/python/typing_extensions/issues/{}', 'issue #')) - app.add_role('issue-cpy', autolink('https://github.com/python/cpython/issues/{}', "CPython issue #")) + app.add_role( + "pr", autolink("https://github.com/python/typing_extensions/pull/{}", "PR #") + ) + app.add_role( + "pr-cpy", autolink("https://github.com/python/cpython/pull/{}", "CPython PR #") + ) + app.add_role( + "issue", + autolink("https://github.com/python/typing_extensions/issues/{}", "issue #"), + ) + app.add_role( + "issue-cpy", + autolink("https://github.com/python/cpython/issues/{}", "CPython issue #"), + ) + def autolink(pattern: str, prefix: str): def role(name, rawtext, text: str, lineno, inliner, options={}, content=[]): url = pattern.format(text) node = nodes.reference(rawtext, f"{prefix}{text}", refuri=url, **options) return [node], [] + return role From 314c104fa75651d5cd7e16fe719e71313091c148 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Sun, 21 May 2023 15:39:35 -0700 Subject: [PATCH 13/13] lint --- doc/_extensions/gh_link.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/_extensions/gh_link.py b/doc/_extensions/gh_link.py index 35968a83..3442dbd3 100644 --- a/doc/_extensions/gh_link.py +++ b/doc/_extensions/gh_link.py @@ -19,7 +19,9 @@ def setup(app): def autolink(pattern: str, prefix: str): - def role(name, rawtext, text: str, lineno, inliner, options={}, content=[]): + def role(name, rawtext, text: str, lineno, inliner, options=None, content=None): + if options is None: + options = {} url = pattern.format(text) node = nodes.reference(rawtext, f"{prefix}{text}", refuri=url, **options) return [node], []