Sandbox::https://github.com/python/python-docs-es/blob/3.14/library/annotationlib.po

Repository navigation

985 lines (844 loc) · 34.5 KB
# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2001 Python Software Foundation
# This file is distributed under the same license as the Python en Español
# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
"Project-Id-Version: Python en Español 3.14\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2026-02-26 18:44-0300\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language: es\n"
"Language-Team: es <LL@li.org>\n"
"Plural-Forms: nplurals=2; plural=(n != 1);\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Generated-By: Babel 2.18.0\n"
#: ../Doc/library/annotationlib.rst:2
msgid ":mod:`!annotationlib` --- Functionality for introspecting annotations"
#: ../Doc/library/annotationlib.rst:9
msgid "**Source code:** :source:`Lib/annotationlib.py`"
#: ../Doc/library/annotationlib.rst:18
"The :mod:`!annotationlib` module provides tools for introspecting :term:"
"`annotations <annotation>` on modules, classes, and functions."
#: ../Doc/library/annotationlib.rst:21
"Annotations are :ref:`lazily evaluated <lazy-evaluation>` and often contain "
"forward references to objects that are not yet defined when the annotation "
"is created. This module provides a set of low-level tools that can be used "
"to retrieve annotations in a reliable way, even in the presence of forward "
"references and other edge cases."
#: ../Doc/library/annotationlib.rst:26
"This module supports retrieving annotations in three main formats (see :"
"class:`Format`), each of which works best for different use cases:"
#: ../Doc/library/annotationlib.rst:29
":attr:`~Format.VALUE` evaluates the annotations and returns their value. "
"This is most straightforward to work with, but it may raise errors, for "
"example if the annotations contain references to undefined names."
#: ../Doc/library/annotationlib.rst:32
":attr:`~Format.FORWARDREF` returns :class:`ForwardRef` objects for "
"annotations that cannot be resolved, allowing you to inspect the annotations "
"without evaluating them. This is useful when you need to work with "
"annotations that may contain unresolved forward references."
#: ../Doc/library/annotationlib.rst:36
":attr:`~Format.STRING` returns the annotations as a string, similar to how "
"it would appear in the source file. This is useful for documentation "
"generators that want to display annotations in a readable way."
#: ../Doc/library/annotationlib.rst:40
"The :func:`get_annotations` function is the main entry point for retrieving "
"annotations. Given a function, class, or module, it returns an annotations "
"dictionary in the requested format. This module also provides functionality "
"for working directly with the :term:`annotate function` that is used to "
"evaluate annotations, such as :func:`get_annotate_from_class_namespace` and :"
"func:`call_annotate_function`, as well as the :func:`call_evaluate_function` "
"function for working with :term:`evaluate functions <evaluate function>`."
#: ../Doc/library/annotationlib.rst:51
"Most functionality in this module can execute arbitrary code; see :ref:`the "
"security section <annotationlib-security>` for more information."
#: ../Doc/library/annotationlib.rst:56
":pep:`649` proposed the current model for how annotations work in Python."
#: ../Doc/library/annotationlib.rst:58
":pep:`749` expanded on various aspects of :pep:`649` and introduced the :mod:"
"`!annotationlib` module."
#: ../Doc/library/annotationlib.rst:61
":ref:`annotations-howto` provides best practices for working with "
"annotations."
#: ../Doc/library/annotationlib.rst:64
":pypi:`typing-extensions` provides a backport of :func:`get_annotations` "
"that works on earlier versions of Python."
#: ../Doc/library/annotationlib.rst:68
msgid "Annotation semantics"
#: ../Doc/library/annotationlib.rst:70
"The way annotations are evaluated has changed over the history of Python 3, "
"and currently still depends on a :ref:`future import <future>`. There have "
"been execution models for annotations:"
#: ../Doc/library/annotationlib.rst:74
"*Stock semantics* (default in Python 3.0 through 3.13; see :pep:`3107` and :"
"pep:`526`): Annotations are evaluated eagerly, as they are encountered in "
"the source code."
#: ../Doc/library/annotationlib.rst:77
"*Stringified annotations* (used with ``from __future__ import annotations`` "
"in Python 3.7 and newer; see :pep:`563`): Annotations are stored as strings "
#: ../Doc/library/annotationlib.rst:80
"*Deferred evaluation* (default in Python 3.14 and newer; see :pep:`649` and :"
"pep:`749`): Annotations are evaluated lazily, only when they are accessed."
#: ../Doc/library/annotationlib.rst:83
msgid "As an example, consider the following program::"
#: ../Doc/library/annotationlib.rst:85
"def func(a: Cls) -> None:\n"
"    print(a)\n"
"class Cls: pass\n"
"print(func.__annotations__)"
#: ../Doc/library/annotationlib.rst:92
msgid "This will behave as follows:"
#: ../Doc/library/annotationlib.rst:94
"Under stock semantics (Python 3.13 and earlier), it will throw a :exc:"
"`NameError` at the line where ``func`` is defined, because ``Cls`` is an "
"undefined name at that point."
#: ../Doc/library/annotationlib.rst:97
#, python-brace-format
"Under stringified annotations (if ``from __future__ import annotations`` is "
"used), it will print ``{'a': 'Cls', 'return': 'None'}``."
#: ../Doc/library/annotationlib.rst:99
#, python-brace-format
"Under deferred evaluation (Python 3.14 and later), it will print ``{'a': "
"<class 'Cls'>, 'return': None}``."
#: ../Doc/library/annotationlib.rst:102
"Stock semantics were used when function annotations were first introduced in "
"Python 3.0 (by :pep:`3107`) because this was the simplest, most obvious way "
"to implement annotations. The same execution model was used when variable "
"annotations were introduced in Python 3.6 (by :pep:`526`). However, stock "
"semantics caused problems when using annotations as type hints, such as a "
"need to refer to names that are not yet defined when the annotation is "
"encountered. In addition, there were performance problems with executing "
"annotations at module import time. Therefore, in Python 3.7, :pep:`563` "
"introduced the ability to store annotations as strings using the ``from "
"__future__ import annotations`` syntax. The plan at the time was to "
"eventually make this behavior the default, but a problem appeared: "
"stringified annotations are more difficult to process for those who "
"introspect annotations at runtime. An alternative proposal, :pep:`649`, "
"introduced the third execution model, deferred evaluation, and was "
"implemented in Python 3.14. Stringified annotations are still used if ``from "
"__future__ import annotations`` is present, but this behavior will "
"eventually be removed."
#: ../Doc/library/annotationlib.rst:121
msgid "Classes"
#: ../Doc/library/annotationlib.rst:125
"An :class:`~enum.IntEnum` describing the formats in which annotations can be "
"returned. Members of the enum, or their equivalent integer values, can be "
"passed to :func:`get_annotations` and other functions in this module, as "
"well as to :attr:`~object.__annotate__` functions."
#: ../Doc/library/annotationlib.rst:133
msgid "Values are the result of evaluating the annotation expressions."
#: ../Doc/library/annotationlib.rst:138
"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."
#: ../Doc/library/annotationlib.rst:149
"Values are real annotation values (as per :attr:`Format.VALUE` format) for "
"defined values, and :class:`ForwardRef` proxies for undefined values. Real "
"objects may contain references to :class:`ForwardRef` proxy objects."
#: ../Doc/library/annotationlib.rst:157
"Values are the text string of the annotation as it appears in the source "
"code, up to modifications including, but not restricted to, whitespace "
"normalizations and constant values optimizations."
#: ../Doc/library/annotationlib.rst:161
"The exact values of these strings may change in future versions of Python."
#: ../Doc/library/annotationlib.rst:167
msgid "A proxy object for forward references in annotations."
#: ../Doc/library/annotationlib.rst:169
"Instances of this class are returned when the :attr:`~Format.FORWARDREF` "
"format is used and annotations contain a name that cannot be resolved. This "
"can happen when a forward reference is used in an annotation, such as when a "
"class is referenced before it is defined."
#: ../Doc/library/annotationlib.rst:176
"A string containing the code that was evaluated to produce the :class:"
"`~ForwardRef`. The string may not be exactly equivalent to the original "
#: ../Doc/library/annotationlib.rst:182
msgid "Evaluate the forward reference, returning its value."
#: ../Doc/library/annotationlib.rst:184
"If the *format* argument is :attr:`~Format.VALUE` (the default), this method "
"may throw an exception, such as :exc:`NameError`, if the forward reference "
"refers to a name that cannot be resolved. The arguments to this method can "
"be used to provide bindings for names that would otherwise be undefined. If "
"the *format* argument is :attr:`~Format.FORWARDREF`, the method will never "
"throw an exception, but may return a :class:`~ForwardRef` instance. For "
"example, if the forward reference object contains the code "
"``list[undefined]``, where ``undefined`` is a name that is not defined, "
"evaluating it with the :attr:`~Format.FORWARDREF` format will return "
"``list[ForwardRef('undefined')]``. If the *format* argument is :attr:"
"`~Format.STRING`, the method will return :attr:`~ForwardRef.__forward_arg__`."
#: ../Doc/library/annotationlib.rst:196
"The *owner* parameter provides the preferred mechanism for passing scope "
"information to this method. The owner of a :class:`~ForwardRef` is the "
"object that contains the annotation from which the :class:`~ForwardRef` "
"derives, such as a module object, type object, or function object."
#: ../Doc/library/annotationlib.rst:201
"The *globals*, *locals*, and *type_params* parameters provide a more precise "
"mechanism for influencing the names that are available when the :class:"
"`~ForwardRef` is evaluated. *globals* and *locals* are passed to :func:"
"`eval`, representing the global and local namespaces in which the name is "
"evaluated. The *type_params* parameter is relevant for objects created using "
"the native syntax for :ref:`generic classes <generic-classes>` and :ref:"
"`functions <generic-functions>`. It is a tuple of :ref:`type parameters "
"<type-params>` that are in scope while the forward reference is being "
"evaluated. For example, if evaluating a :class:`~ForwardRef` retrieved from "
"an annotation found in the class namespace of a generic class ``C``, "
"*type_params* should be set to ``C.__type_params__``."
#: ../Doc/library/annotationlib.rst:212
":class:`~ForwardRef` instances returned by :func:`get_annotations` retain "
"references to information about the scope they originated from, so calling "
"this method with no further arguments may be sufficient to evaluate such "
"objects. :class:`~ForwardRef` instances created by other means may not have "
"any information about their scope, so passing arguments to this method may "
"be necessary to evaluate them successfully."
#: ../Doc/library/annotationlib.rst:219
"If no *owner*, *globals*, *locals*, or *type_params* are provided and the :"
"class:`~ForwardRef` does not contain information about its origin, empty "
"globals and locals dictionaries are used."
#: ../Doc/library/annotationlib.rst:227
msgid "Functions"
#: ../Doc/library/annotationlib.rst:231
"Convert an annotations dict containing runtime values to a dict containing "
"only strings. If the values are not already strings, they are converted "
"using :func:`type_repr`. This is meant as a helper for user-provided "
"annotate functions that support the :attr:`~Format.STRING` format but do not "
"have access to the code creating the annotations."
#: ../Doc/library/annotationlib.rst:238
"For example, this is used to implement the :attr:`~Format.STRING` for :class:"
"`typing.TypedDict` classes created through the functional syntax:"
#: ../Doc/library/annotationlib.rst:241
#, python-brace-format
">>> from typing import TypedDict\n"
">>> Movie = TypedDict(\"movie\", {\"name\": str, \"year\": int})\n"
">>> get_annotations(Movie, format=Format.STRING)\n"
"{'name': 'str', 'year': 'int'}"
#: ../Doc/library/annotationlib.rst:252
"Call the :term:`annotate function` *annotate* with the given *format*, a "
"member of the :class:`Format` enum, and return the annotations dictionary "
"produced by the function."
#: ../Doc/library/annotationlib.rst:256
"This helper function is required because annotate functions generated by the "
"compiler for functions, classes, and modules only support the :attr:`~Format."
"VALUE` format when called directly. To support other formats, this function "
"calls the annotate function in a special environment that allows it to "
"produce annotations in the other formats. This is a useful building block "
"when implementing functionality that needs to partially evaluate annotations "
"while a class is being constructed."
#: ../Doc/library/annotationlib.rst:265
"*owner* is the object that owns the annotation function, usually a function, "
"class, or module. If provided, it is used in the :attr:`~Format.FORWARDREF` "
"format to produce a :class:`ForwardRef` object that carries more information."
#: ../Doc/library/annotationlib.rst:272
":PEP:`PEP 649 <649#the-stringizer-and-the-fake-globals-environment>` "
"contains an explanation of the implementation technique used by this "
"function."
#: ../Doc/library/annotationlib.rst:280
"Call the :term:`evaluate function` *evaluate* with the given *format*, a "
"member of the :class:`Format` enum, and return the value produced by the "
"function. This is similar to :func:`call_annotate_function`, but the latter "
"always returns a dictionary mapping strings to annotations, while this "
"function returns a single value."
#: ../Doc/library/annotationlib.rst:286
"This is intended for use with the evaluate functions generated for lazily "
"evaluated elements related to type aliases and type parameters:"
#: ../Doc/library/annotationlib.rst:289
msgid ":meth:`typing.TypeAliasType.evaluate_value`, the value of type aliases"
#: ../Doc/library/annotationlib.rst:290
msgid ":meth:`typing.TypeVar.evaluate_bound`, the bound of type variables"
#: ../Doc/library/annotationlib.rst:291
":meth:`typing.TypeVar.evaluate_constraints`, the constraints of type "
"variables"
#: ../Doc/library/annotationlib.rst:293
":meth:`typing.TypeVar.evaluate_default`, the default value of type variables"
#: ../Doc/library/annotationlib.rst:295
":meth:`typing.ParamSpec.evaluate_default`, the default value of parameter "
"specifications"
#: ../Doc/library/annotationlib.rst:297
":meth:`typing.TypeVarTuple.evaluate_default`, the default value of type "
"variable tuples"
#: ../Doc/library/annotationlib.rst:300
"*owner* is the object that owns the evaluate function, such as the type "
"alias or type variable object."
#: ../Doc/library/annotationlib.rst:303
"*format* can be used to control the format in which the value is returned:"
#: ../Doc/library/annotationlib.rst:305
">>> type Alias = undefined\n"
">>> call_evaluate_function(Alias.evaluate_value, Format.VALUE)\n"
"Traceback (most recent call last):\n"
"NameError: name 'undefined' is not defined\n"
">>> call_evaluate_function(Alias.evaluate_value, Format.FORWARDREF)\n"
"ForwardRef('undefined')\n"
">>> call_evaluate_function(Alias.evaluate_value, Format.STRING)\n"
"'undefined'"
#: ../Doc/library/annotationlib.rst:321
"Retrieve the :term:`annotate function` from a class namespace dictionary "
"*namespace*. Return :const:`!None` if the namespace does not contain an "
"annotate function. This is primarily useful before the class has been fully "
"created (e.g., in a metaclass); after the class exists, the annotate "
"function can be retrieved with ``cls.__annotate__``. See :ref:`below "
"<annotationlib-metaclass>` for an example using this function in a metaclass."
#: ../Doc/library/annotationlib.rst:331
msgid "Compute the annotations dict for an object."
#: ../Doc/library/annotationlib.rst:333
"*obj* may be a callable, class, module, or other object with :attr:`~object."
"__annotate__` or :attr:`~object.__annotations__` attributes. Passing any "
"other object raises :exc:`TypeError`."
#: ../Doc/library/annotationlib.rst:337
"The *format* parameter controls the format in which annotations are "
"returned, and must be a member of the :class:`Format` enum or its integer "
"equivalent. The different formats work as follows:"
#: ../Doc/library/annotationlib.rst:341
"VALUE: :attr:`!object.__annotations__` is tried first; if that does not "
"exist, the :attr:`!object.__annotate__` function is called if it exists."
#: ../Doc/library/annotationlib.rst:343
"FORWARDREF: If :attr:`!object.__annotations__` exists and can be evaluated "
"successfully, it is used; otherwise, the :attr:`!object.__annotate__` "
"function is called. If it does not exist either, :attr:`!object."
"__annotations__` is tried again and any error from accessing it is re-raised."
#: ../Doc/library/annotationlib.rst:347
"STRING: If :attr:`!object.__annotate__` exists, it is called first; "
"otherwise, :attr:`!object.__annotations__` is used and stringified using :"
"func:`annotations_to_string`."
#: ../Doc/library/annotationlib.rst:351
"Returns a dict. :func:`!get_annotations` returns a new dict every time it's "
"called; calling it twice on the same object will return two different but "
"equivalent dicts."
#: ../Doc/library/annotationlib.rst:355
msgid "This function handles several details for you:"
#: ../Doc/library/annotationlib.rst:357
"If *eval_str* is true, values of type :class:`!str` will be un-stringized "
"using :func:`eval`. This is intended for use with stringized annotations "
"(``from __future__ import annotations``). It is an error to set *eval_str* "
"to true with formats other than :attr:`Format.VALUE`."
#: ../Doc/library/annotationlib.rst:362
"If *obj* doesn't have an annotations dict, returns an empty dict. (Functions "
"and methods always have an annotations dict; classes, modules, and other "
"types of callables may not.)"
#: ../Doc/library/annotationlib.rst:366
"Ignores inherited annotations on classes, as well as annotations on "
"metaclasses. If a class doesn't have its own annotations dict, returns an "
"empty dict."
#: ../Doc/library/annotationlib.rst:369
"All accesses to object members and dict values are done using ``getattr()`` "
"and ``dict.get()`` for safety."
#: ../Doc/library/annotationlib.rst:372
"*eval_str* controls whether or not values of type :class:`!str` are replaced "
"with the result of calling :func:`eval` on those values:"
#: ../Doc/library/annotationlib.rst:375
"If eval_str is true, :func:`eval` is called on values of type :class:`!str`. "
"(Note that :func:`!get_annotations` doesn't catch exceptions; if :func:"
"`eval` raises an exception, it will unwind the stack past the :func:`!"
"get_annotations` call.)"
#: ../Doc/library/annotationlib.rst:379
"If *eval_str* is false (the default), values of type :class:`!str` are "
"unchanged."
#: ../Doc/library/annotationlib.rst:382
"*globals* and *locals* are passed in to :func:`eval`; see the documentation "
"for :func:`eval` for more information. If *globals* or *locals* is :const:`!"
"None`, this function may replace that value with a context-specific default, "
"contingent on ``type(obj)``:"
#: ../Doc/library/annotationlib.rst:387
msgid "If *obj* is a module, *globals* defaults to ``obj.__dict__``."
#: ../Doc/library/annotationlib.rst:388
"If *obj* is a class, *globals* defaults to ``sys.modules[obj.__module__]."
"__dict__`` and *locals* defaults to the *obj* class namespace."
#: ../Doc/library/annotationlib.rst:391
"If *obj* is a callable, *globals* defaults to :attr:`obj.__globals__ "
"<function.__globals__>`, although if *obj* is a wrapped function (using :"
"func:`functools.update_wrapper`) or a :class:`functools.partial` object, it "
"is unwrapped until a non-wrapped function is found."
#: ../Doc/library/annotationlib.rst:397
"Calling :func:`!get_annotations` is best practice for accessing the "
"annotations dict of any object. See :ref:`annotations-howto` for more "
"information on annotations best practices."
#: ../Doc/library/annotationlib.rst:401
#, python-brace-format
">>> def f(a: int, b: str) -> float:\n"
"...     pass\n"
">>> get_annotations(f)\n"
"{'a': <class 'int'>, 'b': <class 'str'>, 'return': <class 'float'>}"
#: ../Doc/library/annotationlib.rst:412
"Convert an arbitrary Python value to a format suitable for use by the :attr:"
"`~Format.STRING` format. This calls :func:`repr` for most objects, but has "
"special handling for some objects, such as type objects."
#: ../Doc/library/annotationlib.rst:416
"This is meant as a helper for user-provided annotate functions that support "
"the :attr:`~Format.STRING` format but do not have access to the code "
"creating the annotations. It can also be used to provide a user-friendly "
"string representation for other objects that contain values that are "
"commonly encountered in annotations."
#: ../Doc/library/annotationlib.rst:426
msgid "Recipes"
#: ../Doc/library/annotationlib.rst:431
msgid "Using annotations in a metaclass"
#: ../Doc/library/annotationlib.rst:433
"A :ref:`metaclass <metaclasses>` may want to inspect or even modify the "
"annotations in a class body during class creation. Doing so requires "
"retrieving annotations from the class namespace dictionary. For classes "
"created with ``from __future__ import annotations``, the annotations will be "
"in the ``__annotations__`` key of the dictionary. For other classes with "
"annotations, :func:`get_annotate_from_class_namespace` can be used to get "
"the annotate function, and :func:`call_annotate_function` can be used to "
"call it and retrieve the annotations. Using the :attr:`~Format.FORWARDREF` "
"format will usually be best, because this allows the annotations to refer to "
"names that cannot yet be resolved when the class is created."
#: ../Doc/library/annotationlib.rst:444
"To modify the annotations, it is best to create a wrapper annotate function "
"that calls the original annotate function, makes any necessary adjustments, "
"and returns the result."
#: ../Doc/library/annotationlib.rst:448
"Below is an example of a metaclass that filters out all :class:`typing."
"ClassVar` annotations from the class and puts them in a separate attribute:"
#: ../Doc/library/annotationlib.rst:451
#, python-brace-format
"import annotationlib\n"
"import typing\n"
"class ClassVarSeparator(type):\n"
"   def __new__(mcls, name, bases, ns):\n"
"      if \"__annotations__\" in ns:  # from __future__ import annotations\n"
"         annotations = ns[\"__annotations__\"]\n"
"         classvar_keys = {\n"
"            key for key, value in annotations.items()\n"
"            # Use string comparison for simplicity; a more robust solution\n"
"            # could use annotationlib.ForwardRef.evaluate\n"
"            if value.startswith(\"ClassVar\")\n"
"         }\n"
"         classvars = {key: annotations[key] for key in classvar_keys}\n"
"         ns[\"__annotations__\"] = {\n"
"            key: value for key, value in annotations.items()\n"
"            if key not in classvar_keys\n"
"         }\n"
"         wrapped_annotate = None\n"
"      elif annotate := annotationlib.get_annotate_from_class_namespace(ns):\n"
"         annotations = annotationlib.call_annotate_function(\n"
"            annotate, format=annotationlib.Format.FORWARDREF\n"
"         )\n"
"         classvar_keys = {\n"
"            key for key, value in annotations.items()\n"
"            if typing.get_origin(value) is typing.ClassVar\n"
"         }\n"
"         classvars = {key: annotations[key] for key in classvar_keys}\n"
"         def wrapped_annotate(format):\n"
"            annos = annotationlib.call_annotate_function(annotate, format, "
"owner=typ)\n"
"            return {key: value for key, value in annos.items() if key not in "
"classvar_keys}\n"
"      else:  # no annotations\n"
"         classvars = {}\n"
"         wrapped_annotate = None\n"
"      typ = super().__new__(mcls, name, bases, ns)\n"
"      if wrapped_annotate is not None:\n"
"         # Wrap the original __annotate__ with a wrapper that removes "
"ClassVars\n"
"         typ.__annotate__ = wrapped_annotate\n"
"      typ.classvars = classvars  # Store the ClassVars in a separate "
"attribute\n"
"      return typ"
#: ../Doc/library/annotationlib.rst:499
msgid "Limitations of the ``STRING`` format"
#: ../Doc/library/annotationlib.rst:501
"The :attr:`~Format.STRING` format is meant to approximate the source code of "
"the annotation, but the implementation strategy used means that it is not "
"always possible to recover the exact source code."
#: ../Doc/library/annotationlib.rst:505
"First, the stringifier of course cannot recover any information that is not "
"present in the compiled code, including comments, whitespace, "
"parenthesization, and operations that get simplified by the compiler."
#: ../Doc/library/annotationlib.rst:509
"Second, the stringifier can intercept almost all operations that involve "
"names looked up in some scope, but it cannot intercept operations that "
"operate fully on constants. As a corollary, this also means it is not safe "
"to request the ``STRING`` format on untrusted code: Python is powerful "
"enough that it is possible to achieve arbitrary code execution even with no "
"access to any globals or builtins. For example:"
#: ../Doc/library/annotationlib.rst:515
#, python-brace-format
">>> def f(x: (1).__class__.__base__.__subclasses__()[-1].__init__."
"__builtins__[\"print\"](\"Hello world\")): pass\n"
">>> annotationlib.get_annotations(f, format=annotationlib.Format.STRING)\n"
"Hello world\n"
"{'x': 'None'}"
#: ../Doc/library/annotationlib.rst:524
"This particular example works as of the time of writing, but it relies on "
"implementation details and is not guaranteed to work in the future."
#: ../Doc/library/annotationlib.rst:527
"Among the different kinds of expressions that exist in Python, as "
"represented by the :mod:`ast` module, some expressions are supported, "
"meaning that the ``STRING`` format can generally recover the original source "
"code; others are unsupported, meaning that they may result in incorrect "
"output or an error."
#: ../Doc/library/annotationlib.rst:532
msgid "The following are supported (sometimes with caveats):"
#: ../Doc/library/annotationlib.rst:534
msgid ":class:`ast.BinOp`"
#: ../Doc/library/annotationlib.rst:535
msgid ":class:`ast.UnaryOp`"
#: ../Doc/library/annotationlib.rst:537
":class:`ast.Invert` (``~``), :class:`ast.UAdd` (``+``), and :class:`ast."
"USub` (``-``) are supported"
#: ../Doc/library/annotationlib.rst:538
msgid ":class:`ast.Not` (``not``) is not supported"
#: ../Doc/library/annotationlib.rst:540
msgid ":class:`ast.Dict` (except when using ``**`` unpacking)"
#: ../Doc/library/annotationlib.rst:541
msgid ":class:`ast.Set`"
#: ../Doc/library/annotationlib.rst:542
msgid ":class:`ast.Compare`"
#: ../Doc/library/annotationlib.rst:544
msgid ":class:`ast.Eq` and :class:`ast.NotEq` are supported"
#: ../Doc/library/annotationlib.rst:545
":class:`ast.Lt`, :class:`ast.LtE`, :class:`ast.Gt`, and :class:`ast.GtE` are "
"supported, but the operand may be flipped"
#: ../Doc/library/annotationlib.rst:546
":class:`ast.Is`, :class:`ast.IsNot`, :class:`ast.In`, and :class:`ast.NotIn` "
"are not supported"
#: ../Doc/library/annotationlib.rst:548
msgid ":class:`ast.Call` (except when using ``**`` unpacking)"
#: ../Doc/library/annotationlib.rst:549
":class:`ast.Constant` (though not the exact representation of the constant; "
"for example, escape sequences in strings are lost; hexadecimal numbers are "
"converted to decimal)"
#: ../Doc/library/annotationlib.rst:551
msgid ":class:`ast.Attribute` (assuming the value is not a constant)"
#: ../Doc/library/annotationlib.rst:552
msgid ":class:`ast.Subscript` (assuming the value is not a constant)"
#: ../Doc/library/annotationlib.rst:553
msgid ":class:`ast.Starred` (``*`` unpacking)"
#: ../Doc/library/annotationlib.rst:554
msgid ":class:`ast.Name`"
#: ../Doc/library/annotationlib.rst:555
msgid ":class:`ast.List`"
#: ../Doc/library/annotationlib.rst:556
msgid ":class:`ast.Tuple`"
#: ../Doc/library/annotationlib.rst:557
msgid ":class:`ast.Slice`"
#: ../Doc/library/annotationlib.rst:559
"The following are unsupported, but throw an informative error when "
"encountered by the stringifier:"
#: ../Doc/library/annotationlib.rst:562
":class:`ast.FormattedValue` (f-strings; error is not detected if conversion "
"specifiers like ``!r`` are used)"
#: ../Doc/library/annotationlib.rst:564
msgid ":class:`ast.JoinedStr` (f-strings)"
#: ../Doc/library/annotationlib.rst:566
msgid "The following are unsupported and result in incorrect output:"
#: ../Doc/library/annotationlib.rst:568
msgid ":class:`ast.BoolOp` (``and`` and ``or``)"
#: ../Doc/library/annotationlib.rst:569
msgid ":class:`ast.IfExp`"
#: ../Doc/library/annotationlib.rst:570
msgid ":class:`ast.Lambda`"
#: ../Doc/library/annotationlib.rst:571
msgid ":class:`ast.ListComp`"
#: ../Doc/library/annotationlib.rst:572
msgid ":class:`ast.SetComp`"
#: ../Doc/library/annotationlib.rst:573
msgid ":class:`ast.DictComp`"
#: ../Doc/library/annotationlib.rst:574
msgid ":class:`ast.GeneratorExp`"
#: ../Doc/library/annotationlib.rst:576
"The following are disallowed in annotation scopes and therefore not relevant:"
#: ../Doc/library/annotationlib.rst:578
msgid ":class:`ast.NamedExpr` (``:=``)"
#: ../Doc/library/annotationlib.rst:579
msgid ":class:`ast.Await`"
#: ../Doc/library/annotationlib.rst:580
msgid ":class:`ast.Yield`"
#: ../Doc/library/annotationlib.rst:581
msgid ":class:`ast.YieldFrom`"
#: ../Doc/library/annotationlib.rst:585
msgid "Limitations of the ``FORWARDREF`` format"
#: ../Doc/library/annotationlib.rst:587
"The :attr:`~Format.FORWARDREF` format aims to produce real values as much as "
"possible, with anything that cannot be resolved replaced with :class:"
"`ForwardRef` objects. It is affected by broadly the same Limitations as the :"
"attr:`~Format.STRING` format: annotations that perform operations on "
"literals or that use unsupported expression types may raise exceptions when "
"evaluated using the :attr:`~Format.FORWARDREF` format."
#: ../Doc/library/annotationlib.rst:594
msgid "Below are a few examples of the behavior with unsupported expressions:"
#: ../Doc/library/annotationlib.rst:596
#, python-brace-format
">>> from annotationlib import get_annotations, Format\n"
">>> def zerodiv(x: 1 / 0): ...\n"
">>> get_annotations(zerodiv, format=Format.STRING)\n"
"Traceback (most recent call last):\n"
"ZeroDivisionError: division by zero\n"
">>> get_annotations(zerodiv, format=Format.FORWARDREF)\n"
"Traceback (most recent call last):\n"
"ZeroDivisionError: division by zero\n"
">>> def ifexp(x: 1 if y else 0): ...\n"
">>> get_annotations(ifexp, format=Format.STRING)\n"
"{'x': '1'}"
#: ../Doc/library/annotationlib.rst:615
msgid "Security implications of introspecting annotations"
#: ../Doc/library/annotationlib.rst:617
"Much of the functionality in this module involves executing code related to "
"annotations, which can then do arbitrary things. For example, :func:"
"`get_annotations` may call an arbitrary :term:`annotate function`, and :meth:"
"`ForwardRef.evaluate` 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, and for various "
"functions in the :mod:`typing` module that work with annotations, such as :"
"func:`typing.get_type_hints`."
#: ../Doc/library/annotationlib.rst:626
"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` "
FilesExpand file tree

annotationlib.po

Latest commit

History

annotationlib.po

File metadata and controls
