annotations.po

# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2001-2022, Python Software Foundation
# This file is distributed under the same license as the Python package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
msgid ""
msgstr ""
"Project-Id-Version: Python 3.13\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2024-09-27 00:14+0000\n"
"PO-Revision-Date: 2023-11-08 23:11+0800\n"
"Last-Translator: rockleon <therockleona@gmail.com>\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"
"X-Generator: Poedit 3.4.1\n"

#: ../../howto/annotations.rst:5
msgid "Annotations Best Practices"
msgstr "註釋 (annotation) 最佳實踐"

#: ../../howto/annotations.rst:0
msgid "author"
msgstr "作者"

#: ../../howto/annotations.rst:7
msgid "Larry Hastings"
msgstr "Larry Hastings"

#: ../../howto/annotations.rst:-1
msgid "Abstract"
msgstr "摘要"

#: ../../howto/annotations.rst:11
msgid ""
"This document is designed to encapsulate the best practices for working with "
"annotations dicts.  If you write Python code that examines "
"``__annotations__`` on Python objects, we encourage you to follow the "
"guidelines described below."
msgstr ""
"本文件旨在封裝 (encapsulate) 使用註釋字典 (annotations dicts) 的最佳實踐。如"
"果你寫 Python 程式碼並在調查 Python 物件上的 ``__annotations__`` ，我們鼓勵你"
"遵循下面描述的準則。"

#: ../../howto/annotations.rst:16
msgid ""
"The document is organized into four sections: best practices for accessing "
"the annotations of an object in Python versions 3.10 and newer, best "
"practices for accessing the annotations of an object in Python versions 3.9 "
"and older, other best practices for ``__annotations__`` that apply to any "
"Python version, and quirks of ``__annotations__``."
msgstr ""
"本文件分為四個部分：在 Python 3.10 及更高版本中存取物件註釋的最佳實踐、在 "
"Python 3.9 及更早版本中存取物件註釋的最佳實踐、適用於任何Python 版本 "
"``__annotations__`` 的最佳實踐，以及 ``__annotations__`` 的奇異之處。"

#: ../../howto/annotations.rst:26
msgid ""
"Note that this document is specifically about working with "
"``__annotations__``, not uses *for* annotations. If you're looking for "
"information on how to use \"type hints\" in your code, please see the :mod:"
"`typing` module."
msgstr ""
"請注意，本文件是特別說明 ``__annotations__`` 的使用，而非\\ *如何使用*\\ 註"
"釋。如果你正在尋找如何在你的程式碼中使用「型別提示 (type hint)」的資訊，請查"
"閱模組 (module) :mod:`typing`。"

#: ../../howto/annotations.rst:33
msgid "Accessing The Annotations Dict Of An Object In Python 3.10 And Newer"
msgstr "在 Python 3.10 及更高版本中存取物件的註釋字典"

#: ../../howto/annotations.rst:35
msgid ""
"Python 3.10 adds a new function to the standard library: :func:`inspect."
"get_annotations`.  In Python versions 3.10 and newer, calling this function "
"is the best practice for accessing the annotations dict of any object that "
"supports annotations.  This function can also \"un-stringize\" stringized "
"annotations for you."
msgstr ""
"Python 3.10 在標準函式庫中新增了一個新函式：:func:`inspect.get_annotations`。"
"在 Python 3.10 及更高版本中，呼叫此函式是存取任何支援註釋的物件的註釋字典的最"
"佳實踐。此函式也可以為你「取消字串化 (un-stringize)」字串化註釋。"

#: ../../howto/annotations.rst:42
msgid ""
"If for some reason :func:`inspect.get_annotations` isn't viable for your use "
"case, you may access the ``__annotations__`` data member manually.  Best "
"practice for this changed in Python 3.10 as well: as of Python 3.10, ``o."
"__annotations__`` is guaranteed to *always* work on Python functions, "
"classes, and modules.  If you're certain the object you're examining is one "
"of these three *specific* objects, you may simply use ``o.__annotations__`` "
"to get at the object's annotations dict."
msgstr ""
"若由於某種原因 :func:`inspect.get_annotations` 對你的場合不可行，你可以手動存"
"取 ``__annotations__`` 資料成員。 Python 3.10 中的最佳實踐也已經改變：從 "
"Python 3.10 開始，保證 ``o.__annotations__`` \\ *始終*\\ 適用於 Python 函式、"
"類別 (class) 和模組。如果你確定正在檢查的物件是這三個\\ *特定*\\ 物件之一，你"
"可以簡單地使用 ``o.__annotations__`` 來取得物件的註釋字典。"

#: ../../howto/annotations.rst:52
msgid ""
"However, other types of callables--for example, callables created by :func:"
"`functools.partial`--may not have an ``__annotations__`` attribute defined.  "
"When accessing the ``__annotations__`` of a possibly unknown object,  best "
"practice in Python versions 3.10 and newer is to call :func:`getattr` with "
"three arguments, for example ``getattr(o, '__annotations__', None)``."
msgstr ""
"但是，其他型別的 callable（可呼叫物件）（例如，由 :func:`functools.partial` "
"建立的 callable）可能沒有定義 ``__annotations__`` 屬性 (attribute)。當存取可"
"能未知的物件的 ``__annotations__`` 時，Python 3.10 及更高版本中的最佳實踐是使"
"用三個參數呼叫 :func:`getattr`，例如 ``getattr(o, '__annotations__', "
"None)``。"

#: ../../howto/annotations.rst:60
msgid ""
"Before Python 3.10, accessing ``__annotations__`` on a class that defines no "
"annotations but that has a parent class with annotations would return the "
"parent's ``__annotations__``. In Python 3.10 and newer, the child class's "
"annotations will be an empty dict instead."
msgstr ""
"在 Python 3.10 之前，存取未定義註釋但具有註釋的父類別的類別上的 "
"``__annotations__`` 將傳回父類別的 ``__annotations__``。在 Python 3.10 及更高"
"版本中，子類別的註釋將會是一個空字典。"

#: ../../howto/annotations.rst:68
msgid "Accessing The Annotations Dict Of An Object In Python 3.9 And Older"
msgstr "在 Python 3.9 及更早版本中存取物件的註釋字典"

#: ../../howto/annotations.rst:70
msgid ""
"In Python 3.9 and older, accessing the annotations dict of an object is much "
"more complicated than in newer versions. The problem is a design flaw in "
"these older versions of Python, specifically to do with class annotations."
msgstr ""
"在 Python 3.9 及更早版本中，存取物件的註釋字典比新版本複雜得多。問題出在於這"
"些舊版 Python 中有設計缺陷，特別是與類別註釋有關的設計缺陷。"

#: ../../howto/annotations.rst:75
msgid ""
"Best practice for accessing the annotations dict of other objects--"
"functions, other callables, and modules--is the same as best practice for "
"3.10, assuming you aren't calling :func:`inspect.get_annotations`: you "
"should use three-argument :func:`getattr` to access the object's "
"``__annotations__`` attribute."
msgstr ""
"存取其他物件（如函式、其他 callable 和模組）的註釋字典的最佳實踐與 3.10 的最"
"佳實踐相同，假設你沒有呼叫 :func:`inspect.get_annotations`：你應該使用三個："
"參數 :func:`getattr` 來存取物件的 ``__annotations__`` 屬性。"

#: ../../howto/annotations.rst:82
msgid ""
"Unfortunately, this isn't best practice for classes.  The problem is that, "
"since ``__annotations__`` is optional on classes, and because classes can "
"inherit attributes from their base classes, accessing the "
"``__annotations__`` attribute of a class may inadvertently return the "
"annotations dict of a *base class.* As an example::"
msgstr ""
"不幸的是，這不是類別的最佳實踐。問題是，由於 ``__annotations__`` 在類別上是選"
"填的 (optional)，並且因為類別可以從其基底類別 (base class) 繼承屬性，所以存取"
"類別的 ``__annotations__`` 屬性可能會無意中回傳\\ *基底類別的註釋字典。*\\ 舉"
"例來說： ::"

#: ../../howto/annotations.rst:89
msgid ""
"class Base:\n"
"    a: int = 3\n"
"    b: str = 'abc'\n"
"\n"
"class Derived(Base):\n"
"    pass\n"
"\n"
"print(Derived.__annotations__)"
msgstr ""
"class Base:\n"
"    a: int = 3\n"
"    b: str = 'abc'\n"
"\n"
"class Derived(Base):\n"
"    pass\n"
"\n"
"print(Derived.__annotations__)"

#: ../../howto/annotations.rst:98
msgid "This will print the annotations dict from ``Base``, not ``Derived``."
msgstr "這將印出 (print) 來自 ``Base`` 的註釋字典，而不是 ``Derived``。"

#: ../../howto/annotations.rst:101
msgid ""
"Your code will have to have a separate code path if the object you're "
"examining is a class (``isinstance(o, type)``). In that case, best practice "
"relies on an implementation detail of Python 3.9 and before: if a class has "
"annotations defined, they are stored in the class's :attr:`~type.__dict__` "
"dictionary.  Since the class may or may not have annotations defined, best "
"practice is to call the :meth:`~dict.get` method on the class dict."
msgstr ""
"如果你正在檢查的物件是一個類別 (``isinstance(o, type)``)，你的程式碼將必須有"
"一個單獨的程式碼路徑。在這種情況下，最佳實踐依賴 Python 3.9 及之前版本的實作"
"細節 (implementation detail)：如果一個類別定義了註釋，它們將儲存在該類別的 :"
"attr:`~type.__dict__` 字典中。由於類別可能定義了註釋，也可能沒有定義，因此最"
"佳實踐是在類別字典上呼叫 :meth:`~dict.get` 方法。"

#: ../../howto/annotations.rst:109
msgid ""
"To put it all together, here is some sample code that safely accesses the "
"``__annotations__`` attribute on an arbitrary object in Python 3.9 and "
"before::"
msgstr ""
"總而言之，以下是一些範例程式碼，可以安全地存取 Python 3.9 及先前版本中任意物"
"件上的 ``__annotations__`` 屬性："

#: ../../howto/annotations.rst:113
msgid ""
"if isinstance(o, type):\n"
"    ann = o.__dict__.get('__annotations__', None)\n"
"else:\n"
"    ann = getattr(o, '__annotations__', None)"
msgstr ""
"if isinstance(o, type):\n"
"    ann = o.__dict__.get('__annotations__', None)\n"
"else:\n"
"    ann = getattr(o, '__annotations__', None)"

#: ../../howto/annotations.rst:118
msgid ""
"After running this code, ``ann`` should be either a dictionary or ``None``.  "
"You're encouraged to double-check the type of ``ann`` using :func:"
"`isinstance` before further examination."
msgstr ""
"運行此程式碼後，``ann`` 應該是字典或 ``None``。我們鼓勵你在進一步檢查之前使"
"用 :func:`isinstance` 仔細檢查 ``ann`` 的型別。"

#: ../../howto/annotations.rst:123
msgid ""
"Note that some exotic or malformed type objects may not have a :attr:`~type."
"__dict__` attribute, so for extra safety you may also wish to use :func:"
"`getattr` to access :attr:`!__dict__`."
msgstr ""
"請注意，某些外來 (exotic) 或格式錯誤 (malform) 的型別物件可能沒有 :attr:"
"`~type.__dict__` 屬性，因此為了額外的安全，你可能還希望使用 :func:`getattr` "
"來存取 :attr:`!__dict__`。"

#: ../../howto/annotations.rst:129
msgid "Manually Un-Stringizing Stringized Annotations"
msgstr "手動取消字串化註釋"

#: ../../howto/annotations.rst:131
msgid ""
"In situations where some annotations may be \"stringized\", and you wish to "
"evaluate those strings to produce the Python values they represent, it "
"really is best to call :func:`inspect.get_annotations` to do this work for "
"you."
msgstr ""
"在某些註釋可能被「字串化」的情況下，並且你希望評估這些字串以產生它們表示的 "
"Python 值，最好呼叫 :func:`inspect.get_annotations` 來為你完成這項工作。"

#: ../../howto/annotations.rst:137
msgid ""
"If you're using Python 3.9 or older, or if for some reason you can't use :"
"func:`inspect.get_annotations`, you'll need to duplicate its logic.  You're "
"encouraged to examine the implementation of :func:`inspect.get_annotations` "
"in the current Python version and follow a similar approach."
msgstr ""
"如果你使用的是 Python 3.9 或更早版本，或者由於某種原因你無法使用 :func:"
"`inspect.get_annotations`，則需要複製其邏輯。我們鼓勵你檢查目前 Python 版本"
"中 :func:`inspect.get_annotations` 的實作並遵循類似的方法。"

#: ../../howto/annotations.rst:143
msgid ""
"In a nutshell, if you wish to evaluate a stringized annotation on an "
"arbitrary object ``o``:"
msgstr "簡而言之，如果你希望評估任意物件 ``o`` 上的字串化註釋： ::"

#: ../../howto/annotations.rst:146
msgid ""
"If ``o`` is a module, use ``o.__dict__`` as the ``globals`` when calling :"
"func:`eval`."
msgstr ""
"如果 ``o`` 是一個模組，則在呼叫 :func:`eval` 時使用 ``o.__dict__`` 作為\\ ``"
"全域變數``。"

#: ../../howto/annotations.rst:148
msgid ""
"If ``o`` is a class, use ``sys.modules[o.__module__].__dict__`` as the "
"``globals``, and ``dict(vars(o))`` as the ``locals``, when calling :func:"
"`eval`."
msgstr ""
"如果 ``o`` 是一個類別，當呼叫 :func:`eval` 時，則使用 ``sys.modules[o."
"__module__].__dict__`` 作為\\ ``全域變數``，使用 ``dict(vars(o))`` 作為\\ ``"
"區域變數``。"

#: ../../howto/annotations.rst:151
msgid ""
"If ``o`` is a wrapped callable using :func:`functools.update_wrapper`, :func:"
"`functools.wraps`, or :func:`functools.partial`, iteratively unwrap it by "
"accessing either ``o.__wrapped__`` or ``o.func`` as appropriate, until you "
"have found the root unwrapped function."
msgstr ""
"如果 ``o`` 是使用 :func:`functools.update_wrapper`、:func:`functools.wraps` "
"或 :func:`functools.partial` 包裝的 callable ，請依據需求，透過存取 ``o."
"__wrapped__`` 或 ``o.func`` 來疊代解開它，直到找到根解包函式。"

#: ../../howto/annotations.rst:155
msgid ""
"If ``o`` is a callable (but not a class), use :attr:`o.__globals__ <function."
"__globals__>` as the globals when calling :func:`eval`."
msgstr ""
"如果 ``o`` 是 callable（但不是類別），則在呼叫 :func:`eval` 時使用 :attr:`o."
"__globals__ <function.__globals__>` 作為全域變數。"

#: ../../howto/annotations.rst:159
msgid ""
"However, not all string values used as annotations can be successfully "
"turned into Python values by :func:`eval`. String values could theoretically "
"contain any valid string, and in practice there are valid use cases for type "
"hints that require annotating with string values that specifically *can't* "
"be evaluated.  For example:"
msgstr ""
"然而，並非所有用作註釋的字串值都可以透過 :func:`eval` 成功轉換為 Python 值。"
"理論上，字串值可以包含任何有效的字串，並且在實踐中，型別提示存在有效的用例，"
"需要使用特定「無法」評估的字串值進行註釋。例如： ::"

#: ../../howto/annotations.rst:166
msgid ""
":pep:`604` union types using ``|``, before support for this was added to "
"Python 3.10."
msgstr ""
"在 Python 3.10 支援 :pep:`604` 聯合型別 (union type) ``|`` 之前使用它。"

#: ../../howto/annotations.rst:168
msgid ""
"Definitions that aren't needed at runtime, only imported when :const:`typing."
"TYPE_CHECKING` is true."
msgstr ""
"Runtime 中不需要的定義，僅在 :const:`typing.TYPE_CHECKING` 為 true 時匯入。"

#: ../../howto/annotations.rst:171
msgid ""
"If :func:`eval` attempts to evaluate such values, it will fail and raise an "
"exception.  So, when designing a library API that works with annotations, "
"it's recommended to only attempt to evaluate string values when explicitly "
"requested to by the caller."
msgstr ""
"如果 :func:`eval` 嘗試計算這類型的值，它將失敗並引發例外。因此，在設計使用註"
"釋的函式庫 API 時，建議僅在呼叫者 (caller) 明確請求時嘗試評估字串值。"

#: ../../howto/annotations.rst:179
msgid "Best Practices For ``__annotations__`` In Any Python Version"
msgstr "任何 Python 版本中 ``__annotations__`` 的最佳實踐"

#: ../../howto/annotations.rst:181
msgid ""
"You should avoid assigning to the ``__annotations__`` member of objects "
"directly.  Let Python manage setting ``__annotations__``."
msgstr ""
"你應該避免直接指派給物件的 ``__annotations__`` 成員。讓 Python 管理設定 "
"``__annotations__``。"

#: ../../howto/annotations.rst:184
msgid ""
"If you do assign directly to the ``__annotations__`` member of an object, "
"you should always set it to a ``dict`` object."
msgstr ""
"如果你直接指派給物件的 ``__annotations__`` 成員，則應始終將其設為 ``dict`` 物"
"件。"

#: ../../howto/annotations.rst:187
msgid ""
"If you directly access the ``__annotations__`` member of an object, you "
"should ensure that it's a dictionary before attempting to examine its "
"contents."
msgstr ""
"如果直接存取物件的 ``__annotations__`` 成員，則應在嘗試檢查其內容之前確保它是"
"字典。"

#: ../../howto/annotations.rst:191
msgid "You should avoid modifying ``__annotations__`` dicts."
msgstr "你應該避免修改 ``__annotations__`` 字典。"

#: ../../howto/annotations.rst:193
msgid ""
"You should avoid deleting the ``__annotations__`` attribute of an object."
msgstr "你應該避免刪除物件的 ``__annotations__`` 屬性。"

#: ../../howto/annotations.rst:198
msgid "``__annotations__`` Quirks"
msgstr "``__annotations__`` 奇異之處"

#: ../../howto/annotations.rst:200
msgid ""
"In all versions of Python 3, function objects lazy-create an annotations "
"dict if no annotations are defined on that object.  You can delete the "
"``__annotations__`` attribute using ``del fn.__annotations__``, but if you "
"then access ``fn.__annotations__`` the object will create a new empty dict "
"that it will store and return as its annotations.  Deleting the annotations "
"on a function before it has lazily created its annotations dict will throw "
"an ``AttributeError``; using ``del fn.__annotations__`` twice in a row is "
"guaranteed to always throw an ``AttributeError``."
msgstr ""
"在 Python 3 的所有版本中，如果沒有在該物件上定義註釋，則函式物件會延遲建立 "
"(lazy-create) 註釋字典。你可以使用 ``del fn.__annotations__`` 刪除 "
"``__annotations__`` 屬性，但如果你隨後存取 ``fn.__annotations__``，該物件將建"
"立一個新的空字典，它將作為註釋儲存並傳回。在函式延遲建立註釋字典之前刪除函式"
"上的註釋將拋出 ``AttributeError``；連續兩次使用 ``del fn.__annotations__`` 保"
"證總是拋出 ``AttributeError`` 。"

#: ../../howto/annotations.rst:210
msgid ""
"Everything in the above paragraph also applies to class and module objects "
"in Python 3.10 and newer."
msgstr "上一段的所有內容也適用於 Python 3.10 及更高版本中的類別和模組物件。"

#: ../../howto/annotations.rst:213
msgid ""
"In all versions of Python 3, you can set ``__annotations__`` on a function "
"object to ``None``.  However, subsequently accessing the annotations on that "
"object using ``fn.__annotations__`` will lazy-create an empty dictionary as "
"per the first paragraph of this section.  This is *not* true of modules and "
"classes, in any Python version; those objects permit setting "
"``__annotations__`` to any Python value, and will retain whatever value is "
"set."
msgstr ""
"在 Python 3 的所有版本中，你可以將函式物件上的 ``__annotations__`` 設定為 "
"``None``。但是，隨後使用 ``fn.__annotations__`` 存取該物件上的註釋將根據本節"
"第一段的內容延遲建立一個空字典。對於任何 Python 版本中的模組和類別來說，情況"
"\\ *並非如此*\\；這些物件允許將  ``__annotations__`` 設定為任何 Python 值，並"
"且將保留設定的任何值。"

#: ../../howto/annotations.rst:221
msgid ""
"If Python stringizes your annotations for you (using ``from __future__ "
"import annotations``), and you specify a string as an annotation, the string "
"will itself be quoted.  In effect the annotation is quoted *twice.*  For "
"example::"
msgstr ""
"如果 Python 為你字串化你的註釋（使用 ``from __future__ import "
"annotations``），並且你指定一個字串作為註釋，則該字串本身將被引用。實際上，註"
"釋被引用了\\ *兩次。*\\ 例如： ::"

#: ../../howto/annotations.rst:227
msgid ""
"from __future__ import annotations\n"
"def foo(a: \"str\"): pass\n"
"\n"
"print(foo.__annotations__)"
msgstr ""
"from __future__ import annotations\n"
"def foo(a: \"str\"): pass\n"
"\n"
"print(foo.__annotations__)"

#: ../../howto/annotations.rst:232
msgid ""
"This prints ``{'a': \"'str'\"}``.  This shouldn't really be considered a "
"\"quirk\"; it's mentioned here simply because it might be surprising."
msgstr ""
"這會印出 ``{'a': \"'str'\"}``。這不應該被認為是一個「奇異的事」，他在這裡被簡"
"單提及，因為他可能會讓人意想不到。"