# Copyright (C) 2001 Python Software Foundation

# This file is distributed under the same license as the Python package.

# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.

#

#, fuzzy

msgid ""

msgstr ""

"Project-Id-Version: Python 3.14\n"

"Report-Msgid-Bugs-To: \n"

"POT-Creation-Date: 2025-10-22 00:14+0000\n"

"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"

"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"

"Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-"

"tw)\n"

"Language: zh_TW\n"

"MIME-Version: 1.0\n"

"Content-Type: text/plain; charset=UTF-8\n"

"Content-Transfer-Encoding: 8bit\n"

#: ../../library/annotationlib.rst:2

msgid ":mod:`!annotationlib` --- Functionality for introspecting annotations"

msgstr ":mod:`!annotationlib` --- 用於自我檢查註釋的功能"

#: ../../library/annotationlib.rst:9

msgid "**Source code:** :source:`Lib/annotationlib.py`"

msgstr "**原始碼：** :source:`Lib/annotationlib.py`"

#: ../../library/annotationlib.rst:18

msgid ""

"The :mod:`!annotationlib` module provides tools for introspecting :term:"

"`annotations <annotation>` on modules, classes, and functions."

msgstr ""

#: ../../library/annotationlib.rst:21

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:26

msgid ""

"This module supports retrieving annotations in three main formats (see :"

"class:`Format`), each of which works best for different use cases:"

msgstr ""

#: ../../library/annotationlib.rst:29

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:32

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:36

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:40

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:51

msgid ""

"Most functionality in this module can execute arbitrary code; see :ref:`the "

"security section <annotationlib-security>` for more information."

msgstr ""

#: ../../library/annotationlib.rst:56

msgid ""

":pep:`649` proposed the current model for how annotations work in Python."

msgstr ""

#: ../../library/annotationlib.rst:58

msgid ""

":pep:`749` expanded on various aspects of :pep:`649` and introduced the :mod:"

"`!annotationlib` module."

msgstr ""

#: ../../library/annotationlib.rst:61

msgid ""

":ref:`annotations-howto` provides best practices for working with "

"annotations."

msgstr ""

#: ../../library/annotationlib.rst:64

msgid ""

":pypi:`typing-extensions` provides a backport of :func:`get_annotations` "

"that works on earlier versions of Python."

msgstr ""

#: ../../library/annotationlib.rst:68

msgid "Annotation semantics"

msgstr ""

#: ../../library/annotationlib.rst:70

msgid ""

"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:"

msgstr ""

#: ../../library/annotationlib.rst:74

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:77

msgid ""

"*Stringified annotations* (used with ``from __future__ import annotations`` "

"in Python 3.7 and newer; see :pep:`563`): Annotations are stored as strings "

"only."

msgstr ""

#: ../../library/annotationlib.rst:80

msgid ""

"*Deferred evaluation* (default in Python 3.14 and newer; see :pep:`649` and :"

"pep:`749`): Annotations are evaluated lazily, only when they are accessed."

msgstr ""

#: ../../library/annotationlib.rst:83

msgid "As an example, consider the following program::"

msgstr ""

#: ../../library/annotationlib.rst:85

msgid ""

"def func(a: Cls) -> None:\n"

" print(a)\n"

"\n"

"class Cls: pass\n"

"\n"

"print(func.__annotations__)"

msgstr ""

"def func(a: Cls) -> None:\n"

" print(a)\n"

"\n"

"class Cls: pass\n"

"\n"

"print(func.__annotations__)"

#: ../../library/annotationlib.rst:92

msgid "This will behave as follows:"

msgstr "這會有以下行為："

#: ../../library/annotationlib.rst:94

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:97

msgid ""

"Under stringified annotations (if ``from __future__ import annotations`` is "

"used), it will print ``{'a': 'Cls', 'return': 'None'}``."

msgstr ""

#: ../../library/annotationlib.rst:99

msgid ""

"Under deferred evaluation (Python 3.14 and later), it will print ``{'a': "

"<class 'Cls'>, 'return': None}``."

msgstr ""

#: ../../library/annotationlib.rst:102

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:121

msgid "Classes"

msgstr ""

#: ../../library/annotationlib.rst:125

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:133

msgid "Values are the result of evaluating the annotation expressions."

msgstr ""

#: ../../library/annotationlib.rst:138

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:149

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:157

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:161

msgid ""

"The exact values of these strings may change in future versions of Python."

msgstr ""

#: ../../library/annotationlib.rst:167

msgid "A proxy object for forward references in annotations."

msgstr ""

#: ../../library/annotationlib.rst:169

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:176

msgid ""

"A string containing the code that was evaluated to produce the :class:"

"`~ForwardRef`. The string may not be exactly equivalent to the original "

"source."

msgstr ""

#: ../../library/annotationlib.rst:182

msgid "Evaluate the forward reference, returning its value."

msgstr ""

#: ../../library/annotationlib.rst:184

msgid ""

"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__`."

msgstr ""

#: ../../library/annotationlib.rst:196

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:201

msgid ""

"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__``."

msgstr ""

#: ../../library/annotationlib.rst:212

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:219

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:227

msgid "Functions"

msgstr ""

#: ../../library/annotationlib.rst:231

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:238

msgid ""

"For example, this is used to implement the :attr:`~Format.STRING` for :class:"

"`typing.TypedDict` classes created through the functional syntax:"

msgstr ""

#: ../../library/annotationlib.rst:241

msgid ""

">>> from typing import TypedDict\n"

">>> Movie = TypedDict(\"movie\", {\"name\": str, \"year\": int})\n"

">>> get_annotations(Movie, format=Format.STRING)\n"

"{'name': 'str', 'year': 'int'}"

msgstr ""

">>> from typing import TypedDict\n"

">>> Movie = TypedDict(\"movie\", {\"name\": str, \"year\": int})\n"

">>> get_annotations(Movie, format=Format.STRING)\n"

"{'name': 'str', 'year': 'int'}"

#: ../../library/annotationlib.rst:252

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:256

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:265

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:272

msgid ""

":PEP:`PEP 649 <649#the-stringizer-and-the-fake-globals-environment>` "

"contains an explanation of the implementation technique used by this "

"function."

msgstr ""

#: ../../library/annotationlib.rst:280

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:286

msgid ""

"This is intended for use with the evaluate functions generated for lazily "

"evaluated elements related to type aliases and type parameters:"

msgstr ""

#: ../../library/annotationlib.rst:289

msgid ":meth:`typing.TypeAliasType.evaluate_value`, the value of type aliases"

msgstr ""

#: ../../library/annotationlib.rst:290

msgid ":meth:`typing.TypeVar.evaluate_bound`, the bound of type variables"

msgstr ""

#: ../../library/annotationlib.rst:291

msgid ""

":meth:`typing.TypeVar.evaluate_constraints`, the constraints of type "

"variables"

msgstr ""

#: ../../library/annotationlib.rst:293

msgid ""

":meth:`typing.TypeVar.evaluate_default`, the default value of type variables"

msgstr ""

#: ../../library/annotationlib.rst:295

msgid ""

":meth:`typing.ParamSpec.evaluate_default`, the default value of parameter "

"specifications"

msgstr ""

#: ../../library/annotationlib.rst:297

msgid ""

":meth:`typing.TypeVarTuple.evaluate_default`, the default value of type "

"variable tuples"

msgstr ""

#: ../../library/annotationlib.rst:300

msgid ""

"*owner* is the object that owns the evaluate function, such as the type "

"alias or type variable object."

msgstr ""

#: ../../library/annotationlib.rst:303

msgid ""

"*format* can be used to control the format in which the value is returned:"

msgstr ""

#: ../../library/annotationlib.rst:305

msgid ""

">>> type Alias = undefined\n"

">>> call_evaluate_function(Alias.evaluate_value, Format.VALUE)\n"

"Traceback (most recent call last):\n"

"...\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'"

msgstr ""

#: ../../library/annotationlib.rst:321

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:331

msgid "Compute the annotations dict for an object."

msgstr ""

#: ../../library/annotationlib.rst:333

msgid ""

"*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`."

msgstr ""

#: ../../library/annotationlib.rst:337

msgid ""

"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:"

msgstr ""

#: ../../library/annotationlib.rst:341

msgid ""

"VALUE: :attr:`!object.__annotations__` is tried first; if that does not "

"exist, the :attr:`!object.__annotate__` function is called if it exists."

msgstr ""

#: ../../library/annotationlib.rst:344

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:349

msgid ""

"When calling :attr:`!object.__annotate__` it is first called with :attr:"

"`~Format.FORWARDREF`. If this is not implemented, it will then check if :"

"attr:`~Format.VALUE_WITH_FAKE_GLOBALS` is supported and use that in the fake "

"globals environment. If neither of these formats are supported, it will fall "

"back to using :attr:`~Format.VALUE`. If :attr:`~Format.VALUE` fails, the "

"error from this call will be raised."

msgstr ""

#: ../../library/annotationlib.rst:355

msgid ""

"STRING: If :attr:`!object.__annotate__` exists, it is called first; "

"otherwise, :attr:`!object.__annotations__` is used and stringified using :"

"func:`annotations_to_string`."

msgstr ""

#: ../../library/annotationlib.rst:359

msgid ""

"When calling :attr:`!object.__annotate__` it is first called with :attr:"

"`~Format.STRING`. If this is not implemented, it will then check if :attr:"

"`~Format.VALUE_WITH_FAKE_GLOBALS` is supported and use that in the fake "

"globals environment. If neither of these formats are supported, it will fall "

"back to using :attr:`~Format.VALUE` with the result converted using :func:"

"`annotations_to_string`. If :attr:`~Format.VALUE` fails, the error from this "

"call will be raised."

msgstr ""

#: ../../library/annotationlib.rst:366

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:370

msgid "This function handles several details for you:"

msgstr ""

#: ../../library/annotationlib.rst:372

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:377

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:381

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:384

msgid ""

"All accesses to object members and dict values are done using ``getattr()`` "

"and ``dict.get()`` for safety."

msgstr ""

#: ../../library/annotationlib.rst:387

msgid ""

"*eval_str* controls whether or not values of type :class:`!str` are replaced "

"with the result of calling :func:`eval` on those values:"

msgstr ""

#: ../../library/annotationlib.rst:390

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:394

msgid ""

"If *eval_str* is false (the default), values of type :class:`!str` are "

"unchanged."

msgstr ""

#: ../../library/annotationlib.rst:397

msgid ""

"*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)``:"

msgstr ""

#: ../../library/annotationlib.rst:402

msgid "If *obj* is a module, *globals* defaults to ``obj.__dict__``."

msgstr "如果 *obj* 是模組，則 *globals* 預設為 ``obj.__dict__``。"

#: ../../library/annotationlib.rst:403

msgid ""

"If *obj* is a class, *globals* defaults to ``sys.modules[obj.__module__]."

"__dict__`` and *locals* defaults to the *obj* class namespace."

msgstr ""

#: ../../library/annotationlib.rst:406

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:412

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:416

msgid ""

">>> def f(a: int, b: str) -> float:\n"

"... pass\n"

">>> get_annotations(f)\n"

"{'a': <class 'int'>, 'b': <class 'str'>, 'return': <class 'float'>}"

msgstr ""

">>> def f(a: int, b: str) -> float:\n"

"... pass\n"

">>> get_annotations(f)\n"

"{'a': <class 'int'>, 'b': <class 'str'>, 'return': <class 'float'>}"

#: ../../library/annotationlib.rst:427

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:431

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:441

msgid "Recipes"

msgstr ""

#: ../../library/annotationlib.rst:446

msgid "Using annotations in a metaclass"

msgstr ""

#: ../../library/annotationlib.rst:448

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:459

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:463

msgid ""

"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:"

msgstr ""

#: ../../library/annotationlib.rst:466

msgid ""

"import annotationlib\n"

"import typing\n"

"\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"

"\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"

"\n"

" else: # no annotations\n"

" classvars = {}\n"

" wrapped_annotate = None\n"

" typ = super().__new__(mcls, name, bases, ns)\n"

"\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"

msgstr ""

#: ../../library/annotationlib.rst:514

msgid "Limitations of the ``STRING`` format"

msgstr "``STRING`` 格式的限制"

#: ../../library/annotationlib.rst:516

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:520

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:524

msgid ""

"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:"

msgstr ""

#: ../../library/annotationlib.rst:530

msgid ""

">>> def f(x: (1).__class__.__base__.__subclasses__()[-1].__init__."

"__builtins__[\"print\"](\"Hello world\")): pass\n"

"...\n"

">>> annotationlib.get_annotations(f, format=annotationlib.Format.STRING)\n"

"Hello world\n"

"{'x': 'None'}"

msgstr ""

">>> def f(x: (1).__class__.__base__.__subclasses__()[-1].__init__."

"__builtins__[\"print\"](\"Hello world\")): pass\n"

"...\n"

">>> annotationlib.get_annotations(f, format=annotationlib.Format.STRING)\n"

"Hello world\n"

"{'x': 'None'}"

#: ../../library/annotationlib.rst:539

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:542

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:547

msgid "The following are supported (sometimes with caveats):"

msgstr ""

#: ../../library/annotationlib.rst:549

msgid ":class:`ast.BinOp`"

msgstr ":class:`ast.BinOp`"

#: ../../library/annotationlib.rst:550

msgid ":class:`ast.UnaryOp`"

msgstr ":class:`ast.UnaryOp`"

#: ../../library/annotationlib.rst:552

msgid ""

":class:`ast.Invert` (``~``), :class:`ast.UAdd` (``+``), and :class:`ast."

"USub` (``-``) are supported"

msgstr ""

":class:`ast.Invert` (``~``)、:class:`ast.UAdd` (``+``) 和 :class:`ast.USub` (``-``) 有被支援"

#: ../../library/annotationlib.rst:553

msgid ":class:`ast.Not` (``not``) is not supported"

msgstr ":class:`ast.Not` (``not``) 並不被支援"

#: ../../library/annotationlib.rst:555

msgid ":class:`ast.Dict` (except when using ``**`` unpacking)"

msgstr ":class:`ast.Dict`\\ （除了使用 ``**`` 解包的情況）"

#: ../../library/annotationlib.rst:556

msgid ":class:`ast.Set`"

msgstr ":class:`ast.Set`"

#: ../../library/annotationlib.rst:557

msgid ":class:`ast.Compare`"

msgstr ":class:`ast.Compare`"

#: ../../library/annotationlib.rst:559

msgid ":class:`ast.Eq` and :class:`ast.NotEq` are supported"

msgstr ":class:`ast.Eq` 和 :class:`ast.NotEq` 有被支援"

#: ../../library/annotationlib.rst:560

msgid ""

":class:`ast.Lt`, :class:`ast.LtE`, :class:`ast.Gt`, and :class:`ast.GtE` are "

"supported, but the operand may be flipped"

msgstr ""

#: ../../library/annotationlib.rst:561

msgid ""

":class:`ast.Is`, :class:`ast.IsNot`, :class:`ast.In`, and :class:`ast.NotIn` "

"are not supported"

msgstr ""

#: ../../library/annotationlib.rst:563

msgid ":class:`ast.Call` (except when using ``**`` unpacking)"

msgstr ""

#: ../../library/annotationlib.rst:564

msgid ""

":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)"

msgstr ""

#: ../../library/annotationlib.rst:566

msgid ":class:`ast.Attribute` (assuming the value is not a constant)"

msgstr ""

#: ../../library/annotationlib.rst:567

msgid ":class:`ast.Subscript` (assuming the value is not a constant)"

msgstr ""

#: ../../library/annotationlib.rst:568

msgid ":class:`ast.Starred` (``*`` unpacking)"

msgstr ""

#: ../../library/annotationlib.rst:569

msgid ":class:`ast.Name`"

msgstr ":class:`ast.Name`"

#: ../../library/annotationlib.rst:570

msgid ":class:`ast.List`"

msgstr ":class:`ast.List`"

#: ../../library/annotationlib.rst:571

msgid ":class:`ast.Tuple`"

msgstr ":class:`ast.Tuple`"

#: ../../library/annotationlib.rst:572

msgid ":class:`ast.Slice`"

msgstr ":class:`ast.Slice`"

#: ../../library/annotationlib.rst:574

msgid ""

"The following are unsupported, but throw an informative error when "

"encountered by the stringifier:"

msgstr ""

#: ../../library/annotationlib.rst:577

msgid ""

":class:`ast.FormattedValue` (f-strings; error is not detected if conversion "

"specifiers like ``!r`` are used)"

msgstr ""

#: ../../library/annotationlib.rst:579

msgid ":class:`ast.JoinedStr` (f-strings)"

msgstr ":class:`ast.JoinedStr`\\ （f 字串）"

#: ../../library/annotationlib.rst:581

msgid "The following are unsupported and result in incorrect output:"

msgstr "以下是不支援的，並且會導致不正確的輸出："

#: ../../library/annotationlib.rst:583

msgid ":class:`ast.BoolOp` (``and`` and ``or``)"

msgstr ":class:`ast.BoolOp`\\ （``and`` 和 ``or``）"

#: ../../library/annotationlib.rst:584

msgid ":class:`ast.IfExp`"

msgstr ":class:`ast.IfExp`"

#: ../../library/annotationlib.rst:585

msgid ":class:`ast.Lambda`"

msgstr ":class:`ast.Lambda`"

#: ../../library/annotationlib.rst:586

msgid ":class:`ast.ListComp`"

msgstr ":class:`ast.ListComp`"

#: ../../library/annotationlib.rst:587

msgid ":class:`ast.SetComp`"

msgstr ":class:`ast.SetComp`"

#: ../../library/annotationlib.rst:588

msgid ":class:`ast.DictComp`"

msgstr ":class:`ast.DictComp`"

#: ../../library/annotationlib.rst:589

msgid ":class:`ast.GeneratorExp`"

msgstr ":class:`ast.GeneratorExp`"

#: ../../library/annotationlib.rst:591

msgid ""

"The following are disallowed in annotation scopes and therefore not relevant:"

msgstr ""

#: ../../library/annotationlib.rst:593

msgid ":class:`ast.NamedExpr` (``:=``)"

msgstr ":class:`ast.NamedExpr` (``:=``)"

#: ../../library/annotationlib.rst:594

msgid ":class:`ast.Await`"

msgstr ":class:`ast.Await`"

#: ../../library/annotationlib.rst:595

msgid ":class:`ast.Yield`"

msgstr ":class:`ast.Yield`"

#: ../../library/annotationlib.rst:596

msgid ":class:`ast.YieldFrom`"

msgstr ":class:`ast.YieldFrom`"

#: ../../library/annotationlib.rst:600

msgid "Limitations of the ``FORWARDREF`` format"

msgstr "``FORWARDREF`` 格式的限制"

#: ../../library/annotationlib.rst:602

msgid ""

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

msgstr ""

#: ../../library/annotationlib.rst:609

msgid "Below are a few examples of the behavior with unsupported expressions:"

msgstr ""

#: ../../library/annotationlib.rst:611

msgid ""

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

" ...\n"

"ZeroDivisionError: division by zero\n"

">>> get_annotations(zerodiv, format=Format.FORWARDREF)\n"

"Traceback (most recent call last):\n"

" ...\n"

"ZeroDivisionError: division by zero\n"

">>> def ifexp(x: 1 if y else 0): ...\n"

">>> get_annotations(ifexp, format=Format.STRING)\n"

"{'x': '1'}"

msgstr ""

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

" ...\n"

"ZeroDivisionError: division by zero\n"

">>> get_annotations(zerodiv, format=Format.FORWARDREF)\n"

"Traceback (most recent call last):\n"

" ...\n"

"ZeroDivisionError: division by zero\n"

">>> def ifexp(x: 1 if y else 0): ...\n"