.. 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.
