| .. module:: typing_extensions | |
| Welcome to typing_extensions's documentation! | |
| ============================================= | |
| ``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 | |
| users on previous Python versions to use it too. | |
| - 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 | |
| in a PEP that has been added to the `python/peps <https://github.com/python/peps>`_ | |
| 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. | |
| Bugfixes and new typing features that don't require a PEP may be added to | |
| ``typing_extensions`` once they are merged into CPython's main branch. | |
| ``typing_extensions`` also re-exports all names from the :py:mod:`typing` module, | |
| including those that have always been present in the module. This allows users to | |
| import names from ``typing_extensions`` without having to remember exactly when | |
| each object was added to :py:mod:`typing`. There are a few exceptions: | |
| :py:class:`typing.ByteString`, which is deprecated and due to be removed in Python | |
| 3.14, is not re-exported. Similarly, the ``typing.io`` and ``typing.re`` submodules, | |
| which are removed in Python 3.13, are excluded. | |
| Versioning and backwards compatibility | |
| -------------------------------------- | |
| Starting with version 4.0.0, ``typing_extensions`` uses | |
| `Semantic Versioning <https://semver.org>`_. A changelog is | |
| maintained `on GitHub <https://github.com/python/typing_extensions/blob/main/CHANGELOG.md>`_. | |
| 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. | |
| Feature releases, with version numbers of the form 4.N.0, are made at | |
| irregular intervals when enough new features accumulate. Before a | |
| feature release, at least one release candidate (with a version number | |
| of the form 4.N.0rc1) should be released to give downstream users time | |
| to test. After at least a week of testing, the new feature version | |
| may then be released. If necessary, additional release candidates can | |
| be added. | |
| Bugfix releases, with version numbers of the form 4.N.1 or higher, | |
| may be made if bugs are discovered after a feature release. | |
| We provide no backward compatibility guarantees for prereleases (e.g., | |
| release candidates) and for unreleased code in our Git repository. | |
| Before version 4.0.0, the versioning scheme loosely followed the Python | |
| version from which features were backported; for example, | |
| ``typing_extensions`` 3.10.0.0 was meant to reflect ``typing`` as of | |
| Python 3.10.0. During this period, no changelog was maintained. | |
| In the documentation below, for each object added since version 4.0 | |
| there is a note indicating the version in which it was added. Objects | |
| for which no such note is present have been present since before version 4.0. | |
| Runtime use of types | |
| ~~~~~~~~~~~~~~~~~~~~ | |
| We aim for complete backwards compatibility in terms of the names we export: | |
| code like ``from typing_extensions import X`` that works on one | |
| typing-extensions release will continue to work on the next. | |
| It is more difficult to maintain compatibility for users that introspect | |
| types at runtime, as almost any detail can potentially break compatibility. | |
| Users who introspect types should follow these guidelines to minimize | |
| the risk of compatibility issues: | |
| - Always check for both the :mod:`typing` and ``typing_extensions`` versions | |
| of objects, even if they are currently the same on some Python version. | |
| Future ``typing_extensions`` releases may re-export a separate version of | |
| the object to backport some new feature or bugfix. | |
| - Use public APIs like :func:`get_origin` and :func:`get_original_bases` to | |
| access internal information about types, instead of accessing private | |
| attributes directly. If some information is not available through a public | |
| attribute, consider opening an issue in CPython to add such an API. | |
| Here is an example recipe for a general-purpose function that could be used for | |
| reasonably performant runtime introspection of typing objects. The function | |
| will be resilient against any potential changes in ``typing_extensions`` that | |
| alter whether an object is reimplemented in ``typing_extensions``, rather than | |
| simply being re-exported from the :mod:`typing` module:: | |
| import functools | |
| import typing | |
| import typing_extensions | |
| from typing import Tuple, Any | |
| # Use an unbounded cache for this function, for optimal performance | |
| @functools.lru_cache(maxsize=None) | |
| def get_typing_objects_by_name_of(name: str) -> Tuple[Any, ...]: | |
| result = tuple( | |
| getattr(module, name) | |
| # You could potentially also include mypy_extensions here, | |
| # if your library supports mypy_extensions | |
| for module in (typing, typing_extensions) | |
| if hasattr(module, name) | |
| ) | |
| if not result: | |
| raise ValueError( | |
| f"Neither typing nor typing_extensions has an object called {name!r}" | |
| ) | |
| return result | |
| # Use a cache here as well, but make it a bounded cache | |
| # (the default cache size is 128) | |
| @functools.lru_cache() | |
| def is_typing_name(obj: object, name: str) -> bool: | |
| return any(obj is thing for thing in get_typing_objects_by_name_of(name)) | |
| Example usage:: | |
| >>> import typing, typing_extensions | |
| >>> from functools import partial | |
| >>> from typing_extensions import get_origin | |
| >>> is_literal = partial(is_typing_name, name="Literal") | |
| >>> is_literal(typing.Literal) | |
| True | |
| >>> is_literal(typing_extensions.Literal) | |
| True | |
| >>> is_literal(typing.Any) | |
| False | |
| >>> is_literal(get_origin(typing.Literal[42])) | |
| True | |
| >>> is_literal(get_origin(typing_extensions.Final[int])) | |
| False | |
| Python version support | |
| ---------------------- | |
| ``typing_extensions`` currently supports Python versions 3.9 and higher. In the future, | |
| support for older Python versions will be dropped some time after that version | |
| reaches end of life. | |
| Version compatibility table | |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| The following table lists objects provided by ``typing_extensions`` that | |
| backport or extend features from the standard library, along with the | |
| Python version in which each feature was added to :py:mod:`typing` and the | |
| ``typing_extensions`` release that first included it. | |
| .. list-table:: | |
| :header-rows: 1 | |
| :widths: 25 15 20 15 | |
| * - Object | |
| - In :mod:`typing` (Python) | |
| - In ``typing_extensions`` | |
| - PEP | |
| * - :data:`Annotated` | |
| - 3.9 | |
| - 3.7.4 | |
| - :pep:`593` | |
| * - :data:`Any` (as base class) | |
| - 3.11 | |
| - 4.4.0 | |
| - | |
| * - :class:`Buffer` | |
| - 3.12 | |
| - 4.6.0 | |
| - :pep:`688` | |
| * - :class:`CapsuleType` | |
| - 3.13 | |
| - 4.12.0 | |
| - | |
| * - :data:`Concatenate` | |
| - 3.10 | |
| - 3.7.4 | |
| - :pep:`612` | |
| * - :func:`dataclass_transform` | |
| - 3.11 | |
| - 4.1.0 | |
| - :pep:`681` | |
| * - :func:`deprecated` | |
| - 3.13 | |
| - 4.5.0 | |
| - :pep:`702` | |
| * - :func:`disjoint_base` | |
| - | |
| - 4.15.0 | |
| - :pep:`800` | |
| * - :func:`evaluate_forward_ref` | |
| - 3.14 | |
| - 4.13.0 | |
| - | |
| * - :class:`Format` | |
| - | |
| - 4.13.0 | |
| - :pep:`649` | |
| * - :func:`get_annotations` | |
| - 3.10 | |
| - 4.13.0 | |
| - :pep:`649` | |
| * - :func:`get_original_bases` | |
| - 3.12 | |
| - 4.6.0 | |
| - | |
| * - :func:`get_protocol_members` | |
| - 3.13 | |
| - 4.7.0 | |
| - | |
| * - :data:`Literal` | |
| - 3.8 | |
| - 2.4.0 | |
| - :pep:`586` | |
| * - :data:`LiteralString` | |
| - 3.11 | |
| - 4.1.0 | |
| - :pep:`675` | |
| * - :class:`NamedTuple` (generic) | |
| - 3.11 | |
| - 4.3.0 | |
| - | |
| * - :data:`Never` | |
| - 3.11 | |
| - 4.1.0 | |
| - | |
| * - :class:`NewType` (picklable) | |
| - 3.10 | |
| - 4.6.0 | |
| - | |
| * - :data:`NoDefault` | |
| - 3.13 | |
| - 4.12.0 | |
| - :pep:`696` | |
| * - :data:`NoExtraItems` | |
| - 3.15 | |
| - 4.13.0 | |
| - :pep:`728` | |
| * - :data:`NotRequired` | |
| - 3.11 | |
| - 4.0.0 | |
| - :pep:`655` | |
| * - :class:`ParamSpec` | |
| - 3.10 | |
| - 3.7.4 | |
| - :pep:`612` | |
| * - :class:`Protocol` | |
| - 3.8 | |
| - 2.4.0 | |
| - :pep:`544` | |
| * - :data:`ReadOnly` | |
| - 3.13 | |
| - 4.9.0 | |
| - :pep:`705` | |
| * - :data:`Required` | |
| - 3.11 | |
| - 4.0.0 | |
| - :pep:`655` | |
| * - :data:`Self` | |
| - 3.11 | |
| - 4.0.0 | |
| - :pep:`673` | |
| * - :class:`sentinel` | |
| - 3.15 | |
| - 4.14.0 (originally under the name `Sentinel`) | |
| - :pep:`661` | |
| * - :class:`TypeAliasType` | |
| - 3.12 | |
| - 4.6.0 | |
| - :pep:`695` | |
| * - :data:`TypeForm` | |
| - | |
| - 4.13.0 | |
| - :pep:`747` | |
| * - :data:`TypeGuard` | |
| - 3.10 | |
| - 3.10 | |
| - :pep:`647` | |
| * - :data:`TypeIs` | |
| - 3.13 | |
| - 4.10.0 | |
| - :pep:`742` | |
| * - :class:`TypeVar` (``default``/``infer_variance``) | |
| - 3.12/3.13 | |
| - 4.4.0 | |
| - :pep:`695`, :pep:`696` | |
| * - :class:`TypeVarTuple` | |
| - 3.11 | |
| - 4.1.0 | |
| - :pep:`646` | |
| * - :func:`assert_never` | |
| - 3.11 | |
| - 4.1.0 | |
| - | |
| * - :func:`assert_type` | |
| - 3.11 | |
| - 4.2.0 | |
| - | |
| * - :func:`get_overloads` | |
| - 3.11 | |
| - 4.2.0 | |
| - | |
| * - :func:`is_protocol` | |
| - 3.13 | |
| - 4.7.0 | |
| - | |
| * - :func:`is_typeddict` | |
| - 3.10 | |
| - 4.1.0 | |
| - | |
| * - :func:`reveal_type` | |
| - 3.11 | |
| - 4.1.0 | |
| - | |
| * - :func:`type_repr` | |
| - 3.14 | |
| - 4.15.0 | |
| - | |
| 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` and :pep:`593`. 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:: Concatenate | |
| 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 :pr:`481` for details. | |
| .. data:: Final | |
| See :py:data:`typing.Final` and :pep:`591`. In ``typing`` since 3.8. | |
| .. data:: Literal | |
| 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 | |
| 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 :pr-cpy:`29334`, :pr-cpy:`23294`, and :pr-cpy:`23383`. | |
| .. data:: LiteralString | |
| See :py:data:`typing.LiteralString` and :pep:`675`. 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``\ s was added, and | |
| in 3.12, the ``__orig_bases__`` attribute was added. | |
| .. versionadded:: 4.3.0 | |
| Added to provide support for generic ``NamedTuple``\ s. | |
| .. versionchanged:: 4.6.0 | |
| Support for the ``__orig_bases__`` attribute was added. | |
| .. versionchanged:: 4.7.0 | |
| The undocumented keyword argument syntax for creating NamedTuple classes | |
| (``NT = NamedTuple("NT", x=int)``) is deprecated, and will be disallowed | |
| in Python 3.15. Use the class-based syntax or the functional syntax instead. | |
| .. versionchanged:: 4.7.0 | |
| When using the functional syntax to create a NamedTuple class, failing to | |
| pass a value to the 'fields' parameter (``NT = NamedTuple("NT")``) is | |
| deprecated. Passing ``None`` to the 'fields' parameter | |
| (``NT = NamedTuple("NT", None)``) is also deprecated. Both will be | |
| disallowed in Python 3.15. To create a NamedTuple class with zero fields, | |
| use ``class NT(NamedTuple): pass`` or ``NT = NamedTuple("NT", [])``. | |
| .. 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. | |
| 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 | |
| The improvements from Python 3.10 and 3.11 were backported. | |
| .. data:: NoDefault | |
| See :py:data:`typing.NoDefault`. In ``typing`` since 3.13. | |
| .. versionadded:: 4.12.0 | |
| .. data:: NoExtraItems | |
| A sentinel used when the ``extra_items`` class argument to :class:`TypedDict` is not | |
| provided. In ``typing`` since 3.15. | |
| .. versionadded:: 4.13.0 | |
| .. data:: NotRequired | |
| See :py:data:`typing.NotRequired` and :pep:`655`. In ``typing`` since 3.11. | |
| .. versionadded:: 4.0.0 | |
| .. class:: ParamSpec(name, *, bound=None, covariant=False, | |
| contravariant=False, infer_variance=False, default=NoDefault) | |
| 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`. | |
| 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 (e.g., see :issue:`126`). | |
| .. versionchanged:: 4.4.0 | |
| Added support for the ``default=`` argument. | |
| .. versionchanged:: 4.6.0 | |
| The implementation was changed for compatibility with Python 3.12. | |
| .. versionchanged:: 4.8.0 | |
| Passing an ellipsis literal (``...``) to *default* now works on Python | |
| 3.10 and lower. | |
| .. versionchanged:: 4.12.0 | |
| The :attr:`!__default__` attribute is now set to ``None`` if | |
| ``default=None`` is passed, and to :data:`NoDefault` if no value is passed. | |
| Previously, passing ``None`` would result in :attr:`!__default__` being set | |
| to :py:class:`types.NoneType`, and passing no value for the parameter would | |
| result in :attr:`!__default__` being set to ``None``. | |
| .. versionchanged:: 4.12.0 | |
| ParamSpecs now have a ``has_default()`` method, for compatibility | |
| with :py:class:`typing.ParamSpec` on Python 3.13+. | |
| .. versionchanged:: 4.16.0 | |
| The ``infer_variance``, ``covariant``, and ``contravariant`` arguments are now | |
| officially supported and their validation is improved. | |
| .. class:: ParamSpecArgs | |
| ParamSpecKwargs | |
| See :py:class:`typing.ParamSpecArgs` and :py:class:`typing.ParamSpecKwargs`. | |
| In ``typing`` since 3.10. | |
| .. class:: Protocol | |
| 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. | |
| .. 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, | |
| including :pr-cpy:`103034` and :pr-cpy:`26067`. | |
| .. versionchanged:: 4.7.0 | |
| Classes can now inherit from both :py:class:`typing.Protocol` and | |
| ``typing_extensions.Protocol`` simultaneously. Previously, this led to | |
| :py:exc:`TypeError` being raised due to a metaclass conflict. | |
| It is recommended to avoid doing this if possible. Not all features and | |
| bugfixes that ``typing_extensions.Protocol`` backports from newer Python | |
| versions are guaranteed to work if :py:class:`typing.Protocol` is also | |
| present in a protocol class's :py:term:`method resolution order`. See | |
| :issue:`245` for some examples. | |
| .. data:: ReadOnly | |
| See :py:data:`typing.ReadOnly` and :pep:`705`. In ``typing`` since 3.13. | |
| Indicates that a :class:`TypedDict` item may not be modified. | |
| .. versionadded:: 4.9.0 | |
| .. data:: Required | |
| See :py:data:`typing.Required` and :pep:`655`. In ``typing`` since 3.11. | |
| .. versionadded:: 4.0.0 | |
| .. data:: Self | |
| See :py:data:`typing.Self` and :pep:`673`. In ``typing`` since 3.11. | |
| .. versionadded:: 4.0.0 | |
| .. data:: TypeAlias | |
| See :py:data:`typing.TypeAlias` and :pep:`613`. In ``typing`` since 3.10. | |
| .. class:: TypeAliasType(name, value, *, type_params=()) | |
| See :py:class:`typing.TypeAliasType` and :pep:`695`. In ``typing`` since 3.12. | |
| .. versionadded:: 4.6.0 | |
| .. data:: TypeForm | |
| See :pep:`747`. A special form representing the value of a type expression. | |
| .. versionadded:: 4.13.0 | |
| .. data:: TypeGuard | |
| See :py:data:`typing.TypeGuard` and :pep:`647`. In ``typing`` since 3.10. | |
| .. data:: TypeIs | |
| See :py:data:`typing.TypeIs` and :pep:`742`. In ``typing`` since 3.13. | |
| Similar to :data:`TypeGuard`, but allows more type narrowing. | |
| .. versionadded:: 4.10.0 | |
| .. class:: TypedDict(dict, total=True, closed=False, extra_items=<no extra items>) | |
| See :py:class:`typing.TypedDict` and :pep:`589`. In ``typing`` since 3.8, but | |
| changed and enhanced in several ways since then. | |
| ``typing_extensions`` backports various bug fixes and improvements | |
| to ``TypedDict``. | |
| Features backported by `typing_extensions` include: | |
| * :py:class:`typing.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()`` on Python 3.9.0 and 3.9.1. | |
| * :py:class:`typing.TypedDict` does not support multiple inheritance with | |
| :py:class:`typing.Generic` on Python <3.11 | |
| * :py:class:`typing.TypedDict` classes do not consistently have the | |
| :attr:`!__orig_bases__` attribute on Python <3.12. | |
| * :py:class:`typing.TypedDict` does not expose the | |
| :py:attr:`~typing.TypedDict.__readonly_keys__` and | |
| :py:attr:`~typing.TypedDict.__mutable_keys__` attributes on Python <3.13. | |
| * :py:class:`typing.TypedDict` does not support the *extra_items* or *closed* | |
| keyword arguments on Python <3.15, and also does not expose the | |
| :py:attr:`~typing.TypedDict.__extra_items__` and | |
| :py:attr:`~typing.TypedDict.__closed__` attributes on Python <3.15. | |
| ``typing_extensions`` also currently includes experimental support for | |
| :pep:`764` (inline ``TypedDict``\ s), which is not yet supported in the | |
| standard library on any Python version. | |
| Historically, ``TypedDict`` has supported an alternative creation syntax | |
| where the fields are supplied as keyword arguments (e.g., | |
| ``TypedDict("TD", a=int, b=str)``). In CPython, this feature was deprecated | |
| in Python 3.11 and removed in Python 3.13. ``typing_extensions.TypedDict`` | |
| raises a :py:exc:`DeprecationWarning` when this syntax is used in Python 3.12 | |
| or lower and fails with a :py:exc:`TypeError` in Python 3.13 and higher. | |
| Introspection attributes | |
| ------------------------ | |
| ``typing_extensions`` supports the :data:`ReadOnly` qualifier | |
| introduced by :pep:`705`. It is reflected in the following attributes: | |
| .. attribute:: __readonly_keys__ | |
| A :py:class:`frozenset` containing the names of all read-only keys. Keys | |
| are read-only if they carry the :data:`ReadOnly` qualifier. | |
| .. versionadded:: 4.9.0 | |
| .. attribute:: __mutable_keys__ | |
| A :py:class:`frozenset` containing the names of all mutable keys. Keys | |
| are mutable if they do not carry the :data:`ReadOnly` qualifier. | |
| .. versionadded:: 4.9.0 | |
| The *closed* and *extra_items* keyword arguments introduced by | |
| :pep:`728` and supported in Python 3.15 and newer are supported. | |
| For runtime introspection, two attributes can be looked at: | |
| .. attribute:: __closed__ | |
| A boolean flag indicating whether the current ``TypedDict`` is | |
| considered closed. This reflects the ``closed`` class argument. | |
| .. versionadded:: 4.10.0 | |
| .. attribute:: __extra_items__ | |
| The type of the extra items allowed on the ``TypedDict``. | |
| This attribute defaults to :data:`NoExtraItems` if the ``extra_items`` | |
| class argument is not provided. | |
| .. versionadded:: 4.10.0 | |
| History | |
| ------- | |
| .. versionchanged:: 4.3.0 | |
| Added support for generic ``TypedDict``\ s. | |
| .. 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. | |
| .. versionchanged:: 4.7.0 | |
| ``TypedDict`` is now a function rather than a class. | |
| This brings ``typing_extensions.TypedDict`` closer to the implementation | |
| of :py:class:`typing.TypedDict` on Python 3.9 and higher. | |
| .. versionchanged:: 4.7.0 | |
| When using the functional syntax to create a TypedDict class, failing to | |
| pass a value to the 'fields' parameter (``TD = TypedDict("TD")``) is | |
| deprecated. Passing ``None`` to the 'fields' parameter | |
| (``TD = TypedDict("TD", None)``) is also deprecated. Both will be | |
| disallowed in Python 3.15. To create a TypedDict class with 0 fields, | |
| use ``class TD(TypedDict): pass`` or ``TD = TypedDict("TD", {})``. | |
| .. versionchanged:: 4.9.0 | |
| Support for the :data:`ReadOnly` qualifier was added. | |
| .. versionchanged:: 4.10.0 | |
| The keyword argument ``closed`` and the special key ``__extra_items__`` | |
| when ``closed=True`` is given were supported. | |
| .. versionchanged:: 4.13.0 | |
| :pep:`728` support was updated to a newer version. Extra items are now | |
| indicated with an ``extra_items`` class argument, not a special key | |
| ``__extra_items__``. | |
| A value assigned to ``__total__`` in the class body of a | |
| ``TypedDict`` will be overwritten by the ``total`` argument of the | |
| ``TypedDict`` constructor. | |
| .. class:: TypeVar(name, *constraints, bound=None, covariant=False, | |
| contravariant=False, infer_variance=False, default=NoDefault) | |
| 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. | |
| .. versionchanged:: 4.12.0 | |
| The :attr:`!__default__` attribute is now set to ``None`` if | |
| ``default=None`` is passed, and to :data:`NoDefault` if no value is passed. | |
| Previously, passing ``None`` would result in :attr:`!__default__` being set | |
| to :py:class:`types.NoneType`, and passing no value for the parameter would | |
| result in :attr:`!__default__` being set to ``None``. | |
| .. versionchanged:: 4.12.0 | |
| TypeVars now have a ``has_default()`` method, for compatibility | |
| with :py:class:`typing.TypeVar` on Python 3.13+. | |
| .. class:: TypeVarTuple(name, *, bound=None, covariant=False, | |
| contravariant=False, infer_variance=False, default=NoDefault) | |
| 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`, and for the ``bound=``, ``infer_variance=``, ``covariant=`` | |
| and ``contravariant=`` arguments that were added in Python 3.15. | |
| .. 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. | |
| .. versionchanged:: 4.12.0 | |
| The :attr:`!__default__` attribute is now set to ``None`` if | |
| ``default=None`` is passed, and to :data:`NoDefault` if no value is passed. | |
| Previously, passing ``None`` would result in :attr:`!__default__` being set | |
| to :py:class:`types.NoneType`, and passing no value for the parameter would | |
| result in :attr:`!__default__` being set to ``None``. | |
| .. versionchanged:: 4.12.0 | |
| TypeVarTuples now have a ``has_default()`` method, for compatibility | |
| with :py:class:`typing.TypeVarTuple` on Python 3.13+. | |
| .. versionchanged:: 4.12.0 | |
| It is now disallowed to use a `TypeVar` with a default value after a | |
| `TypeVarTuple` in a type parameter list. This matches the CPython | |
| implementation of PEP 696 on Python 3.13+. | |
| .. versionchanged:: 4.16.0 | |
| The ``bound``, ``infer_variance``, ``covariant``, and ``contravariant`` | |
| arguments are now supported. | |
| .. data:: Unpack | |
| 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. | |
| Generic type aliases involving ``Unpack`` may not work correctly on | |
| Python 3.10 and lower; see :issue:`103` for details. | |
| .. versionadded:: 4.1.0 | |
| .. versionchanged:: 4.6.0 | |
| Backport ``repr()`` changes from Python 3.12. | |
| Abstract Base Classes | |
| ~~~~~~~~~~~~~~~~~~~~~ | |
| .. class:: Buffer | |
| See :py:class:`collections.abc.Buffer`. Added to the standard library | |
| in Python 3.12. | |
| .. versionadded:: 4.6.0 | |
| Protocols | |
| ~~~~~~~~~ | |
| .. class:: SupportsAbs | |
| See :py:class:`typing.SupportsAbs`. | |
| ``typing_extensions`` backports a more performant version of this | |
| protocol on 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 on 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 on 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 on 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 on 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 on 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 on Python 3.11 and lower. | |
| .. versionadded:: 4.6.0 | |
| .. class:: Reader | |
| See :py:class:`io.Reader`. Added to the standard library in Python 3.14. | |
| .. versionadded:: 4.14.0 | |
| .. class:: Writer | |
| See :py:class:`io.Writer`. Added to the standard library in Python 3.14. | |
| .. versionadded:: 4.14.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` and :pep:`681`. 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 :py:func:`warnings.deprecated` and :pep:`702`. In the :mod:`warnings` module | |
| since Python 3.13. | |
| .. versionadded:: 4.5.0 | |
| .. versionchanged:: 4.9.0 | |
| Inheriting from a deprecated class now also raises a runtime | |
| :py:exc:`DeprecationWarning`. | |
| .. decorator:: disjoint_base | |
| See :pep:`800`. A class decorator that marks a class as a "disjoint base", meaning that | |
| child classes of the decorated class cannot inherit from other disjoint bases that are not | |
| parent classes of the decorated class. | |
| This helps type checkers to detect unreachable code and to understand when two types | |
| can overlap. | |
| .. versionadded:: 4.15.0 | |
| .. decorator:: final | |
| 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`` | |
| backports this feature. | |
| .. versionchanged:: 4.1.0 | |
| The decorator now attempts to set the ``__final__`` attribute 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 | |
| Introspection support via :func:`get_overloads` was added. | |
| .. decorator:: override | |
| See :py:func:`typing.override` and :pep:`698`. In ``typing`` since 3.12. | |
| .. versionadded:: 4.4.0 | |
| .. versionchanged:: 4.5.0 | |
| The decorator now attempts to set 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:: evaluate_forward_ref(forward_ref, *, owner=None, globals=None, locals=None, type_params=None, format=None) | |
| Evaluate an :py:class:`typing.ForwardRef` as a :py:term:`type hint`. | |
| This is similar to calling :py:meth:`annotationlib.ForwardRef.evaluate`, | |
| but unlike that method, :func:`!evaluate_forward_ref` also: | |
| * Recursively evaluates forward references nested within the type hint. | |
| However, the amount of recursion is limited in Python 3.8 and 3.10. | |
| * Raises :exc:`TypeError` when it encounters certain objects that are | |
| not valid type hints. | |
| * Replaces type hints that evaluate to :const:`!None` with | |
| :class:`types.NoneType`. | |
| * Supports the :attr:`Format.FORWARDREF` and | |
| :attr:`Format.STRING` formats. | |
| *forward_ref* must be an instance of :py:class:`typing.ForwardRef`. | |
| *owner*, if given, should be the object that holds the annotations that | |
| the forward reference derived from, such as a module, class object, or function. | |
| It is used to infer the namespaces to use for looking up names. | |
| *globals* and *locals* can also be explicitly given to provide | |
| the global and local namespaces. | |
| *type_params* is a tuple of :py:ref:`type parameters <type-params>` that | |
| are in scope when evaluating the forward reference. | |
| This parameter must be provided (though it may be an empty tuple) if *owner* | |
| is not given and the forward reference does not already have an owner set. | |
| *format* specifies the format of the annotation and is a member of | |
| the :class:`Format` enum, defaulting to :attr:`Format.VALUE`. | |
| .. caution:: | |
| This function may execute arbitrary code contained in annotations. | |
| See :ref:`annotations-security` for more information. | |
| .. versionadded:: 4.13.0 | |
| .. function:: get_annotations(obj, *, globals=None, locals=None, eval_str=False, format=Format.VALUE) | |
| See :py:func:`inspect.get_annotations`. In the standard library since Python 3.10. | |
| ``typing_extensions`` adds the keyword argument ``format``, as specified | |
| by :pep:`649`. The supported formats are listed in the :class:`Format` enum. | |
| The default format, :attr:`Format.VALUE`, behaves the same across all versions. | |
| For the other two formats, ``typing_extensions`` provides a rough approximation | |
| of the :pep:`649` behavior on versions of Python that do not support it. | |
| The purpose of this backport is to allow users who would like to use | |
| :attr:`Format.FORWARDREF` or :attr:`Format.STRING` semantics once | |
| :pep:`649` is implemented, but who also | |
| want to support earlier Python versions, to simply write:: | |
| typing_extensions.get_annotations(obj, format=Format.FORWARDREF) | |
| .. caution:: | |
| This function may execute arbitrary code contained in annotations. | |
| See :ref:`annotations-security` for more information. | |
| .. versionadded:: 4.13.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` classes 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_protocol_members(tp) | |
| See :py:func:`typing.get_protocol_members`. In ``typing`` since 3.13. | |
| Return the set of members defined in a :class:`Protocol`. This works with protocols | |
| defined using either :class:`typing.Protocol` or :class:`typing_extensions.Protocol`. | |
| :: | |
| >>> from typing_extensions import Protocol, get_protocol_members | |
| >>> class P(Protocol): | |
| ... def a(self) -> str: ... | |
| ... b: int | |
| >>> get_protocol_members(P) | |
| frozenset({'a', 'b'}) | |
| Raise :py:exc:`TypeError` for arguments that are not Protocols. | |
| .. versionadded:: 4.7.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` and :py:data:`typing.NotRequired`. | |
| ``typing_extensions`` backports these fixes. | |
| .. caution:: | |
| This function may execute arbitrary code contained in annotations. | |
| See :ref:`annotations-security` for more information. | |
| .. versionchanged:: 4.1.0 | |
| Interaction with :data:`Required` and :data:`NotRequired`. | |
| .. versionchanged:: 4.11.0 | |
| When ``include_extra=False``, ``get_type_hints()`` now strips | |
| :data:`ReadOnly` from the annotation. | |
| .. function:: is_protocol(tp) | |
| See :py:func:`typing.is_protocol`. In ``typing`` since 3.13. | |
| Determine if a type is a :class:`Protocol`. This works with protocols | |
| defined using either :py:class:`typing.Protocol` or :class:`typing_extensions.Protocol`. | |
| For example:: | |
| class P(Protocol): | |
| def a(self) -> str: ... | |
| b: int | |
| is_protocol(P) # => True | |
| is_protocol(int) # => False | |
| .. versionadded:: 4.7.0 | |
| .. 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 mechanism. | |
| .. versionadded:: 4.1.0 | |
| .. versionchanged:: 4.7.0 | |
| :func:`is_typeddict` now returns ``False`` when called with | |
| :data:`TypedDict` itself as the argument, consistent with the | |
| behavior of :py:func:`typing.is_typeddict`. | |
| .. function:: reveal_type(obj) | |
| See :py:func:`typing.reveal_type`. In ``typing`` since 3.11. | |
| .. versionadded:: 4.1.0 | |
| .. function:: type_repr(value) | |
| See :py:func:`annotationlib.type_repr`. In ``annotationlib`` since 3.14. | |
| Convert an arbitrary Python value to a format suitable for use by | |
| the :attr:`Format.STRING`. | |
| .. versionadded:: 4.15.0 | |
| Enums | |
| ~~~~~ | |
| .. class:: Format | |
| The formats for evaluating annotations introduced by :pep:`649`. | |
| Members of this enum can be passed as the *format* argument | |
| to :func:`get_annotations`. | |
| The final place of this enum in the standard library has not yet | |
| been determined (see :pep:`649` and :pep:`749`), but the names | |
| and integer values are stable and will continue to work. | |
| .. attribute:: VALUE | |
| Equal to 1. The default value. The function will return the conventional Python values | |
| for the annotations. This format is identical to the return value for | |
| the function under earlier versions of Python. | |
| .. attribute:: VALUE_WITH_FAKE_GLOBALS | |
| Equal to 2. Special value used to signal that an annotate function is being | |
| evaluated in a special environment with fake globals. When passed this | |
| value, annotate functions should either return the same value as for | |
| the :attr:`Format.VALUE` format, or raise :exc:`NotImplementedError` | |
| to signal that they do not support execution in this environment. | |
| This format is only used internally and should not be passed to | |
| the functions in this module. | |
| .. attribute:: FORWARDREF | |
| Equal to 3. When :pep:`649` is implemented, this format will attempt to return the | |
| conventional Python values for the annotations. However, if it encounters | |
| an undefined name, it dynamically creates a proxy object (a ForwardRef) | |
| that substitutes for that value in the expression. | |
| ``typing_extensions`` emulates this value on versions of Python which do | |
| not support :pep:`649` by returning the same value as for ``VALUE`` semantics. | |
| .. attribute:: STRING | |
| Equal to 4. When :pep:`649` is implemented, this format will produce an annotation | |
| dictionary where the values have been replaced by strings containing | |
| an approximation of the original source code for the annotation expressions. | |
| ``typing_extensions`` emulates this by evaluating the annotations using | |
| ``VALUE`` semantics and then stringifying the results. | |
| .. versionadded:: 4.13.0 | |
| Annotation metadata | |
| ~~~~~~~~~~~~~~~~~~~ | |
| .. class:: Doc(documentation, /) | |
| Define the documentation of a type annotation using :data:`Annotated`, to be | |
| used in class attributes, function and method parameters, return values, | |
| and variables. | |
| The value should be a positional-only string literal to allow static tools | |
| like editors and documentation generators to use it. | |
| This complements docstrings. | |
| The string value passed is available in the attribute ``documentation``. | |
| Example:: | |
| >>> from typing_extensions import Annotated, Doc | |
| >>> def hi(to: Annotated[str, Doc("Who to say hi to")]) -> None: ... | |
| .. versionadded:: 4.8.0 | |
| See :pep:`727`. | |
| .. attribute:: documentation | |
| The documentation string passed to :class:`Doc`. | |
| Capsule objects | |
| ~~~~~~~~~~~~~~~ | |
| .. class:: CapsuleType | |
| The type of :py:ref:`capsule objects <capsules>`. | |
| See :py:class:`types.CapsuleType`, where it has existed since Python 3.13. | |
| Note that this may not exist on all implementations of Python; it is only | |
| guaranteed to exist on CPython. | |
| .. versionadded:: 4.12.0 | |
| Sentinel objects | |
| ~~~~~~~~~~~~~~~~ | |
| .. class:: sentinel(name, /, *, repr=None) | |
| A type used to define sentinel values. The *name* argument should be the | |
| name of the variable to which the return value shall be assigned. | |
| Assigning attributes to a sentinel is deprecated (except for __module__). | |
| Example:: | |
| >>> from typing_extensions import sentinel, assert_type | |
| >>> MISSING = sentinel('MISSING') | |
| >>> def func(arg: int | MISSING = MISSING) -> None: | |
| ... if arg is MISSING: | |
| ... assert_type(arg, MISSING) | |
| ... else: | |
| ... assert_type(arg, int) | |
| ... | |
| >>> func(MISSING) | |
| .. versionadded:: 4.14.0 | |
| See :pep:`661` | |
| .. versionchanged:: 4.16.0 | |
| The implementation of this class has been updated to conform to | |
| the accepted version of :pep:`661`: | |
| - Sentinels can now be pickled. They are reduced as singletons, which | |
| means that they also preserve their identity when copied or deep-copied. | |
| - `Sentinel` has been renamed to `sentinel`. `Sentinel` is retained as a | |
| soft-deprecated alias, for backwards compatibility. | |
| - The default repr of a sentinel `X = sentinel("X")` is now `X`, rather | |
| than `<X>`. | |
| - Passing `repr` as a positional argument to the constructor is deprecated. | |
| - Passing `name` as a keyword argument to the constructor is deprecated. | |
| - Subclassing `sentinel` is deprecated. | |
| - Assigning arbitrary attributes to a sentinel is deprecated. | |
| Pure aliases | |
| ~~~~~~~~~~~~ | |
| Most of these are simply re-exported from the :mod:`typing` module on all supported | |
| versions of Python, but all are listed here for completeness. | |
| .. class:: AbstractSet | |
| See :py:class:`typing.AbstractSet`. | |
| .. versionadded:: 4.7.0 | |
| .. data:: AnyStr | |
| See :py:data:`typing.AnyStr`. | |
| .. versionadded:: 4.7.0 | |
| .. class:: AsyncContextManager | |
| See :py:class:`typing.AsyncContextManager`. In ``typing`` since 3.5.4 and 3.6.2. | |
| .. versionchanged:: 4.12.0 | |
| ``AsyncContextManager`` now has an optional second parameter, defaulting to | |
| ``Optional[bool]``, signifying the return type of the ``__aexit__`` method. | |
| .. class:: AsyncGenerator | |
| See :py:class:`typing.AsyncGenerator`. In ``typing`` since 3.6.1. | |
| .. versionchanged:: 4.12.0 | |
| The second type parameter is now optional (it defaults to ``None``). | |
| .. 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:: BinaryIO | |
| See :py:class:`typing.BinaryIO`. | |
| .. versionadded:: 4.7.0 | |
| .. data:: Callable | |
| See :py:data:`typing.Callable`. | |
| .. versionadded:: 4.7.0 | |
| .. class:: ChainMap | |
| See :py:class:`typing.ChainMap`. In ``typing`` since 3.5.4 and 3.6.1. | |
| .. data:: ClassVar | |
| See :py:data:`typing.ClassVar` and :pep:`526`. In ``typing`` since 3.5.3. | |
| .. class:: Collection | |
| See :py:class:`typing.Collection`. | |
| .. versionadded:: 4.7.0 | |
| .. class:: Container | |
| See :py:class:`typing.Container`. | |
| .. versionadded:: 4.7.0 | |
| .. class:: ContextManager | |
| See :py:class:`typing.ContextManager`. In ``typing`` since 3.5.4. | |
| .. versionchanged:: 4.12.0 | |
| ``ContextManager`` now has an optional second parameter, defaulting to | |
| ``Optional[bool]``, signifying the return type of the ``__exit__`` method. | |
| .. class:: Coroutine | |
| See :py:class:`typing.Coroutine`. In ``typing`` since 3.5.3. | |
| .. 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:: Dict | |
| See :py:class:`typing.Dict`. | |
| .. versionadded:: 4.7.0 | |
| .. class:: ForwardRef | |
| See :py:class:`typing.ForwardRef`. | |
| .. versionadded:: 4.7.0 | |
| .. class:: FrozenSet | |
| See :py:class:`typing.FrozenSet`. | |
| .. versionadded:: 4.7.0 | |
| .. class:: Generator | |
| See :py:class:`typing.Generator`. | |
| .. versionadded:: 4.7.0 | |
| .. versionchanged:: 4.12.0 | |
| The second type and third type parameters are now optional | |
| (they both default to ``None``). | |
| .. class:: Generic | |
| See :py:class:`typing.Generic`. | |
| .. versionadded:: 4.7.0 | |
| .. class:: Hashable | |
| See :py:class:`typing.Hashable`. | |
| .. versionadded:: 4.7.0 | |
| .. class:: IO | |
| See :py:class:`typing.IO`. | |
| .. versionadded:: 4.7.0 | |
| .. class:: ItemsView | |
| See :py:class:`typing.ItemsView`. | |
| .. versionadded:: 4.7.0 | |
| .. class:: Iterable | |
| See :py:class:`typing.Iterable`. | |
| .. versionadded:: 4.7.0 | |
| .. class:: Iterator | |
| See :py:class:`typing.Iterator`. | |
| .. versionadded:: 4.7.0 | |
| .. class:: KeysView | |
| See :py:class:`typing.KeysView`. | |
| .. versionadded:: 4.7.0 | |
| .. class:: List | |
| See :py:class:`typing.List`. | |
| .. versionadded:: 4.7.0 | |
| .. class:: Mapping | |
| See :py:class:`typing.Mapping`. | |
| .. versionadded:: 4.7.0 | |
| .. class:: MappingView | |
| See :py:class:`typing.MappingView`. | |
| .. versionadded:: 4.7.0 | |
| .. class:: Match | |
| See :py:class:`typing.Match`. | |
| .. versionadded:: 4.7.0 | |
| .. class:: MutableMapping | |
| See :py:class:`typing.MutableMapping`. | |
| .. versionadded:: 4.7.0 | |
| .. class:: MutableSequence | |
| See :py:class:`typing.MutableSequence`. | |
| .. versionadded:: 4.7.0 | |
| .. class:: MutableSet | |
| See :py:class:`typing.MutableSet`. | |
| .. versionadded:: 4.7.0 | |
| .. data:: NoReturn | |
| See :py:data:`typing.NoReturn`. In ``typing`` since 3.5.4 and 3.6.2. | |
| .. data:: Optional | |
| See :py:data:`typing.Optional`. | |
| .. versionadded:: 4.7.0 | |
| .. class:: OrderedDict | |
| See :py:class:`typing.OrderedDict`. In ``typing`` since 3.7.2. | |
| .. class:: Pattern | |
| See :py:class:`typing.Pattern`. | |
| .. versionadded:: 4.7.0 | |
| .. class:: Reversible | |
| See :py:class:`typing.Reversible`. | |
| .. versionadded:: 4.7.0 | |
| .. class:: Sequence | |
| See :py:class:`typing.Sequence`. | |
| .. versionadded:: 4.7.0 | |
| .. class:: Set | |
| See :py:class:`typing.Set`. | |
| .. versionadded:: 4.7.0 | |
| .. class:: Sized | |
| See :py:class:`typing.Sized`. | |
| .. versionadded:: 4.7.0 | |
| .. class:: Text | |
| See :py:class:`typing.Text`. In ``typing`` since 3.5.2. | |
| .. class:: TextIO | |
| See :py:class:`typing.TextIO`. | |
| .. versionadded:: 4.7.0 | |
| .. data:: Tuple | |
| See :py:data:`typing.Tuple`. | |
| .. versionadded:: 4.7.0 | |
| .. class:: Type | |
| See :py:class:`typing.Type`. In ``typing`` since 3.5.2. | |
| .. data:: TYPE_CHECKING | |
| See :py:data:`typing.TYPE_CHECKING`. In ``typing`` since 3.5.2. | |
| .. data:: Union | |
| See :py:class:`typing.Union`. | |
| .. versionadded:: 4.7.0 | |
| .. class:: ValuesView | |
| See :py:class:`typing.ValuesView`. | |
| .. versionadded:: 4.7.0 | |
| .. function:: cast | |
| See :py:func:`typing.cast`. | |
| .. versionadded:: 4.7.0 | |
| .. decorator:: no_type_check | |
| See :py:func:`typing.no_type_check`. | |
| .. versionadded:: 4.7.0 | |
| .. decorator:: no_type_check_decorator | |
| See :py:func:`typing.no_type_check_decorator`. | |
| .. versionadded:: 4.7.0 | |
| Security | |
| -------- | |
| ``typing_extensions`` is among the most widely used packages in the | |
| Python ecosystem. Therefore, we take security seriously and strive | |
| to use a transparent, secure release process. | |
| We commit to the following in order to keep the package secure in the | |
| future: | |
| * ``typing_extensions`` will never include any native extensions, only | |
| pure Python code. | |
| * ``typing_extensions`` will not have any third-party dependencies. | |
| * We will follow best practices for a secure release process. | |
| If you have any feedback on our security process, please `open an issue | |
| <https://github.com/python/typing_extensions/issues/new>`__. To report | |
| an issue privately, use `GitHub's private reporting feature | |
| <https://github.com/python/typing_extensions/security>`__. | |
| .. _annotations-security: | |
| Introspection of annotations | |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| Some functions in this module are designed to introspect annotations at | |
| runtime. These functions may therefore execute code contained in annotations, | |
| which can then perform arbitrary operations. For example, | |
| :func:`get_annotations` may call an arbitrary :term:`annotate function`, and | |
| :meth:`evaluate_forward_ref` may call :func:`eval` on an arbitrary string. Code contained | |
| in an annotation might make arbitrary system calls, enter an infinite loop, or perform any | |
| other operation. This is also true for any access of the :attr:`~object.__annotations__` attribute | |
| (as of Python 3.14), | |
| and for various functions in the :mod:`typing` module that work with annotations, such as | |
| :func:`typing.get_type_hints`. | |
| Any security issue arising from this also applies immediately after importing | |
| code that may contain untrusted annotations: importing code can always cause arbitrary operations | |
| to be performed. However, it is unsafe to accept strings or other input from an untrusted source and | |
| pass them to any of the APIs for introspecting annotations, for example by editing an | |
| ``__annotations__`` dictionary or directly creating a :class:`ForwardRef` object. |