Skip to content

docs: add security implications of annotations #727

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
srittau merged 1 commit into from
Jan 28, 2026
+37 −0
Merged

docs: add security implications of annotations #727

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 37 additions & 0 deletions doc/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -815,6 +815,11 @@ Functions
*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)
Expand All @@ -834,6 +839,11 @@ Functions

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)
Expand Down Expand Up @@ -901,6 +911,11 @@ Functions
: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`.
Expand Down Expand Up @@ -1415,3 +1430,25 @@ 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.
Loading