1================= 2Typing Extensions 3================= 4 5.. image:: https://badges.gitter.im/python/typing.svg 6 :alt: Chat at https://gitter.im/python/typing 7 :target: https://gitter.im/python/typing?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge 8 9Overview 10======== 11 12The ``typing_extensions`` module serves two related purposes: 13 14- Enable use of new type system features on older Python versions. For example, 15 ``typing.TypeGuard`` is new in Python 3.10, but ``typing_extensions`` allows 16 users on Python 3.6 through 3.9 to use it too. 17- Enable experimentation with new type system PEPs before they are accepted and 18 added to the ``typing`` module. 19 20New features may be added to ``typing_extensions`` as soon as they are specified 21in a PEP that has been added to the `python/peps <https://github.com/python/peps>`_ 22repository. If the PEP is accepted, the feature will then be added to ``typing`` 23for the next CPython release. No typing PEP has been rejected so far, so we 24haven't yet figured out how to deal with that possibility. 25 26Starting with version 4.0.0, ``typing_extensions`` uses 27`Semantic Versioning <https://semver.org/>`_. The 28major version is incremented for all backwards-incompatible changes. 29Therefore, it's safe to depend 30on ``typing_extensions`` like this: ``typing_extensions >=x.y, <(x+1)``, 31where ``x.y`` is the first version that includes all features you need. 32 33``typing_extensions`` supports Python versions 3.7 and higher. In the future, 34support for older Python versions will be dropped some time after that version 35reaches end of life. 36 37Included items 38============== 39 40This module currently contains the following: 41 42- Experimental features 43 44 - ``@dataclass_transform()`` (see PEP 681) 45 46- In ``typing`` since Python 3.11 47 48 - ``assert_never`` 49 - ``assert_type`` 50 - ``LiteralString`` (see PEP 675) 51 - ``Never`` 52 - ``NotRequired`` (see PEP 655) 53 - ``reveal_type`` 54 - ``Required`` (see PEP 655) 55 - ``Self`` (see PEP 673) 56 - ``TypeVarTuple`` (see PEP 646) 57 - ``Unpack`` (see PEP 646) 58 59- In ``typing`` since Python 3.10 60 61 - ``Concatenate`` (see PEP 612) 62 - ``ParamSpec`` (see PEP 612) 63 - ``ParamSpecArgs`` (see PEP 612) 64 - ``ParamSpecKwargs`` (see PEP 612) 65 - ``TypeAlias`` (see PEP 613) 66 - ``TypeGuard`` (see PEP 647) 67 - ``is_typeddict`` 68 69- In ``typing`` since Python 3.9 70 71 - ``Annotated`` (see PEP 593) 72 73- In ``typing`` since Python 3.8 74 75 - ``final`` (see PEP 591) 76 - ``Final`` (see PEP 591) 77 - ``Literal`` (see PEP 586) 78 - ``Protocol`` (see PEP 544) 79 - ``runtime_checkable`` (see PEP 544) 80 - ``TypedDict`` (see PEP 589) 81 - ``get_origin`` (``typing_extensions`` provides this function only in Python 3.7+) 82 - ``get_args`` (``typing_extensions`` provides this function only in Python 3.7+) 83 84- In ``typing`` since Python 3.7 85 86 - ``OrderedDict`` 87 88- In ``typing`` since Python 3.5 or 3.6 (see `the typing documentation 89 <https://docs.python.org/3.10/library/typing.html>`_ for details) 90 91 - ``AsyncContextManager`` 92 - ``AsyncGenerator`` 93 - ``AsyncIterable`` 94 - ``AsyncIterator`` 95 - ``Awaitable`` 96 - ``ChainMap`` 97 - ``ClassVar`` (see PEP 526) 98 - ``ContextManager`` 99 - ``Coroutine`` 100 - ``Counter`` 101 - ``DefaultDict`` 102 - ``Deque`` 103 - ``NewType`` 104 - ``NoReturn`` 105 - ``overload`` 106 - ``Text`` 107 - ``Type`` 108 - ``TYPE_CHECKING`` 109 - ``get_type_hints`` 110 111Other Notes and Limitations 112=========================== 113 114Certain objects were changed after they were added to ``typing``, and 115``typing_extensions`` provides a backport even on newer Python versions: 116 117- ``TypedDict`` does not store runtime information 118 about which (if any) keys are non-required in Python 3.8, and does not 119 honor the "total" keyword with old-style ``TypedDict()`` in Python 120 3.9.0 and 3.9.1. 121- ``get_origin`` and ``get_args`` lack support for ``Annotated`` in 122 Python 3.8 and lack support for ``ParamSpecArgs`` and ``ParamSpecKwargs`` 123 in 3.9. 124- ``@final`` was changed in Python 3.11 to set the ``.__final__`` attribute. 125 126There are a few types whose interface was modified between different 127versions of typing. For example, ``typing.Sequence`` was modified to 128subclass ``typing.Reversible`` as of Python 3.5.3. 129 130These changes are _not_ backported to prevent subtle compatibility 131issues when mixing the differing implementations of modified classes. 132 133Certain types have incorrect runtime behavior due to limitations of older 134versions of the typing module: 135 136- ``ParamSpec`` and ``Concatenate`` will not work with ``get_args`` and 137 ``get_origin``. Certain PEP 612 special cases in user-defined 138 ``Generic``\ s are also not available. 139 140These types are only guaranteed to work for static type checking. 141 142Running tests 143============= 144 145To run tests, navigate into the appropriate source directory and run 146``test_typing_extensions.py``. 147
