Update library/typing (#691)

rockleona · mattwang44 · web-flow · commit 72726c24edc6 · 2023-11-06T03:24:24.000Z
* Update NewType Section

* Finish translate this section

* Update with reviewer's suggestion

* Update Reviewer's Comment Part 2

* Update library/typing.po

---------

Co-authored-by: Wei-Hsiang (Matt) Wang &lt;mattwang44@gmail.com&gt;
diff --git a/library/typing.po b/library/typing.po
@@ -8,7 +8,7 @@ msgstr ""
 "Project-Id-Version: Python 3.12\n"
 "Report-Msgid-Bugs-To: \n"
 "POT-Creation-Date: 2023-10-25 00:03+0000\n"
-"PO-Revision-Date: 2023-09-05 14:49+0800\n"
+"PO-Revision-Date: 2023-11-06 10:51+0800\n"
 "Last-Translator: RockLeon <therockleona@gmail.com>\n"
 "Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-"
 "tw)\n"
@@ -17,7 +17,7 @@ msgstr ""
 "Content-Type: text/plain; charset=UTF-8\n"
 "Content-Transfer-Encoding: 8bit\n"
 "Plural-Forms: nplurals=1; plural=0;\n"
-"X-Generator: Poedit 3.3.1\n"
+"X-Generator: Poedit 3.4\n"
 
 #: ../../library/typing.rst:3
 msgid ":mod:`typing` --- Support for type hints"
@@ -33,7 +33,7 @@ msgid ""
 "They can be used by third party tools such as type checkers, IDEs, linters, "
 "etc."
 msgstr ""
-"Python 執行環境不強制要求函式與變數的型別註釋。他們可以被第三方工具使用，如："
+"Python runtime 不強制要求函式與變數的型別註釋。他們可以被第三方工具使用，如："
 "型別檢查器、IDE、linter 等。"
 
 #: ../../library/typing.rst:26
@@ -357,13 +357,15 @@ msgstr "NewType"
 
 #: ../../library/typing.rst:179
 msgid "Use the :class:`NewType` helper to create distinct types::"
-msgstr ""
+msgstr "使用 :class:`NewType` 輔助工具 (helper) 建立獨特型別： ::"
 
 #: ../../library/typing.rst:186
 msgid ""
 "The static type checker will treat the new type as if it were a subclass of "
 "the original type. This is useful in helping catch logical errors::"
 msgstr ""
+"若它是原本型別的子類別，靜態型別檢查器會將其視為一個新的型別。這對於幫助擷取"
+"邏輯性錯誤非常有用： ::"
 
 #: ../../library/typing.rst:198
 msgid ""
@@ -372,6 +374,9 @@ msgid ""
 "pass in a ``UserId`` wherever an ``int`` might be expected, but will prevent "
 "you from accidentally creating a ``UserId`` in an invalid way::"
 msgstr ""
+"你依然可以在對於型別 ``UserId`` 的變數中執行所有 ``int`` 的操作。這讓你可以在"
+"預期接受 ``int`` 的地方傳遞一個 ``UserId``，還能預防你意外使用無效的方法建立"
+"一個 ``UserId``： ::"
 
 #: ../../library/typing.rst:206
 msgid ""
@@ -381,26 +386,33 @@ msgid ""
 "it. That means the expression ``Derived(some_value)`` does not create a new "
 "class or introduce much overhead beyond that of a regular function call."
 msgstr ""
+"注意這只會透過靜態型別檢查器強制檢查。在 runtime 中，陳述式 (statement) "
+"``Derived = NewType('Derived', Base)`` 會使 ``Derived`` 成為一個 callable（可"
+"呼叫物件），會立即回傳任何你傳遞的引數。這意味著 expression （運算式）"
+"``Derived(some_value)`` 不會建立一個新的類別或過度引入原有的函式呼叫。"
 
 #: ../../library/typing.rst:212
 msgid ""
 "More precisely, the expression ``some_value is Derived(some_value)`` is "
 "always true at runtime."
 msgstr ""
+"更精確地說，expression ``some_value is Derived(some_value)`` 在 runtime 永遠"
+"為 true。"
 
 #: ../../library/typing.rst:215
 msgid "It is invalid to create a subtype of ``Derived``::"
-msgstr ""
+msgstr "這會無法建立一個 ``Derived`` 的子型別： ::"
 
 #: ../../library/typing.rst:224
 msgid ""
 "However, it is possible to create a :class:`NewType` based on a 'derived' "
 "``NewType``::"
 msgstr ""
+"無論如何，這有辦法基於 '衍生的' ``NewType`` 建立一個 :class:`NewType`： ::"
 
 #: ../../library/typing.rst:232
 msgid "and typechecking for ``ProUserId`` will work as expected."
-msgstr ""
+msgstr "以及針對 ``ProUserId`` 的型別檢查會如期運作。"
 
 #: ../../library/typing.rst:234
 msgid "See :pep:`484` for more details."
@@ -413,6 +425,9 @@ msgid ""
 "checker treat ``Alias`` as being *exactly equivalent* to ``Original`` in all "
 "cases. This is useful when you want to simplify complex type signatures."
 msgstr ""
+"請記得使用型別別名是宣告兩種型別是互相\\ *相等*\\ 的。使用 ``type Alias = "
+"Original`` 則會讓靜態型別檢查器在任何情況之下將 ``Alias`` 視為與 "
+"``Original`` \\ *完全相等*\\ 。這當你想把複雜的型別簽名進行簡化時，非常好用。"
 
 #: ../../library/typing.rst:243
 msgid ""
@@ -423,23 +438,30 @@ msgid ""
 "``Derived`` is expected. This is useful when you want to prevent logic "
 "errors with minimal runtime cost."
 msgstr ""
+"相反的，``NewType`` 宣告一個型別會是另外一種型別的子類別。使用 ``Derived = "
+"NewType('Derived', Original)`` 會使靜態型別檢查器將 ``Derived`` 視為 "
+"``Original`` 的子類別，也意味著一個型別為 ``Original`` 的值，不能被使用在任何"
+"預期接收到型別 ``Derived`` 的值的區域。這當你想用最小的 runtime 成本預防邏輯"
+"性錯誤而言，非常有用。"
 
 #: ../../library/typing.rst:252
 msgid ""
 "``NewType`` is now a class rather than a function.  As a result, there is "
 "some additional runtime cost when calling ``NewType`` over a regular "
 "function."
 msgstr ""
+"現在的 ``NewType`` 比起一個函式更像一個類別。因此，比起一般的函式，呼叫 "
+"``NewType`` 需要額外的 runtime 成本。"
 
 #: ../../library/typing.rst:257
 msgid ""
 "The performance of calling ``NewType`` has been restored to its level in "
 "Python 3.9."
-msgstr ""
+msgstr "呼叫 ``NewType`` 的效能已經恢復與 Python 3.9 相同的水準。"
 
 #: ../../library/typing.rst:264
 msgid "Annotating callable objects"
-msgstr ""
+msgstr "註釋 callable 物件"
 
 #: ../../library/typing.rst:266
 msgid ""
@@ -448,6 +470,9 @@ msgid ""
 "``Callable[[int], str]`` signifies a function that takes a single parameter "
 "of type :class:`int` and returns a :class:`str`."
 msgstr ""
+"函式，或者是其他 :term:`callable` 物件，可以使用 :class:`collections.abc."
+"Callable` 或 :data:`typing.Callable` 進行註釋。 ``Callable[[int], str]`` 象徵"
+"為一個函式，可以接受一個型別為 :class:`int` 的引數，並回傳一個 :class:`str`。"
 
 #: ../../library/typing.rst:271 ../../library/typing.rst:2894
 #: ../../library/typing.rst:3036
@@ -461,12 +486,17 @@ msgid ""
 "types, a :class:`ParamSpec`, :data:`Concatenate`, or an ellipsis. The return "
 "type must be a single type."
 msgstr ""
+"使用下標語法 (subscription syntax) 時，必須使用到兩個值，分別為引述串列以及回"
+"傳類別。引數串列必須為一個型別串列：:class:`ParamSpec`、:data:`Concatenate` "
+"或是一個刪節號 (ellipsis)。回傳類別必為一個單一類別。"
 
 #: ../../library/typing.rst:294
 msgid ""
 "If a literal ellipsis ``...`` is given as the argument list, it indicates "
 "that a callable with any arbitrary parameter list would be acceptable:"
 msgstr ""
+"若刪節號文字 ``...`` 被當作引數串列給定，其指出一個具任何、任意參數列表的 "
+"callable 會被接受： ::"
 
 #: ../../library/typing.rst:306
 msgid ""
@@ -476,6 +506,10 @@ msgid ""
 "be expressed by defining a :class:`Protocol` class with a :meth:`~object."
 "__call__` method:"
 msgstr ""
+"``Callable`` 不如有可變數量引數的函式、:func:`overloaded functions "
+"<overload>`、或是僅限關鍵字參數的函式，可以表示複雜簽名。然而，這些簽名可以透"
+"過定義一個具有 :meth:`~object.__call__` 方法的 :class:`Protocol` 類別進行表"
+"示："
 
 #: ../../library/typing.rst:333
 msgid ""
@@ -487,53 +521,70 @@ msgid ""
 "``Callable[Concatenate[Arg1Type, Arg2Type, ..., ParamSpecVariable], "
 "ReturnType]`` respectively."
 msgstr ""
+"Callable 物件可以取用其他 callable 當作引數使用，可以透過 :class:`ParamSpec` "
+"指出他們的參數型別是個別獨立的。另外，如果這個 callable 從其他 callable 新增"
+"或刪除引數時，將會使用到 :data:`Concatenate` 運算子。他們可以分別採用 "
+"``Callable[ParamSpecVariable, ReturnType]`` 以及 "
+"``Callable[Concatenate[Arg1Type, Arg2Type, ..., ParamSpecVariable], "
+"ReturnType]`` 的形式。"
 
 #: ../../library/typing.rst:341 ../../library/typing.rst:3565
 msgid ""
 "``Callable`` now supports :class:`ParamSpec` and :data:`Concatenate`. See :"
 "pep:`612` for more details."
 msgstr ""
+"``Callable`` 現已支援 :class:`ParamSpec` 以及 :data:`Concatenate`。請參閱 :"
+"pep:`612` 閱讀詳細內容。"
 
 #: ../../library/typing.rst:346
 msgid ""
 "The documentation for :class:`ParamSpec` and :class:`Concatenate` provides "
 "examples of usage in ``Callable``."
 msgstr ""
+":class:`ParamSpec` 以及 :class:`Concatenate` 的文件中，提供範例如何在 "
+"``Callable`` 中使用。"
 
 #: ../../library/typing.rst:352
 msgid "Generics"
-msgstr ""
+msgstr "泛型"
 
 #: ../../library/typing.rst:354
 msgid ""
 "Since type information about objects kept in containers cannot be statically "
 "inferred in a generic way, many container classes in the standard library "
 "support subscription to denote the expected types of container elements."
 msgstr ""
+"因為關於物件的型別資訊留存在容器之內，且無法使用通用的方式進行靜態推論 "
+"(statically inferred)，許多標準函式庫的容器類別支援以下標來表示容器內預期的元"
+"素。"
 
 #: ../../library/typing.rst:371
 msgid ""
 "Generic functions and classes can be parameterized by using :ref:`type "
 "parameter syntax <type-params>`::"
 msgstr ""
+"泛型函式及類別可以使用\\ :ref:`型別參數語法 (type parameter syntax) <type-"
+"params>` 進行參數化 (parameterize) ： ::"
 
 #: ../../library/typing.rst:379
 msgid "Or by using the :class:`TypeVar` factory directly::"
-msgstr ""
+msgstr "或是直接使用 :class:`TypeVar` 工廠 (factory)： ::"
 
 #: ../../library/typing.rst:389
 msgid "Syntactic support for generics is new in Python 3.12."
-msgstr ""
+msgstr "在 Python 3.12 中，泛型的語法支援是全新功能。"
 
 #: ../../library/typing.rst:395
 msgid "Annotating tuples"
-msgstr ""
+msgstr "註釋元組 (tuple)"
 
 #: ../../library/typing.rst:397
 msgid ""
 "For most containers in Python, the typing system assumes that all elements "
 "in the container will be of the same type. For example::"
 msgstr ""
+"在 Python 大多數的容器當中，加註型別系統認為容器內的所有元素會是相同型別。舉"
+"例來說： ::"
 
 #: ../../library/typing.rst:412
 msgid ""
@@ -542,6 +593,10 @@ msgid ""
 "Mapping` only accepts two type arguments: the first indicates the type of "
 "the keys, and the second indicates the type of the values."
 msgstr ""
+":class:`list` 只接受一個型別引數，所以型別檢查器可能在上述 ``y`` 賦值 "
+"(assignment) 觸發錯誤。類似的範例，:class:`~collections.abc.Mapping` 只接受兩"
+"個型別引數：第一個引數指出 keys（鍵）的型別；第二個引數指出 values（值）的型"
+"別。"
 
 #: ../../library/typing.rst:418
 msgid ""
@@ -550,6 +605,10 @@ msgid ""
 "For this reason, tuples are special-cased in Python's typing system. :class:"
 "`tuple` accepts *any number* of type arguments::"
 msgstr ""
+"然而，與其他多數的 Python 容器不同，在慣用的 (idiomatic) Python 程式碼中，元"
+"組可以擁有不完全相同型別的元素是相當常見的。為此，元組在 Python 的加註型別系"
+"統中是個特例 (special-cased)。:class:`tuple` 接受\\ *任何數量*\\ 的型別引"
+"數： ::"
 
 #: ../../library/typing.rst:434
 msgid ""
@@ -558,6 +617,9 @@ msgid ""
 "use ``tuple[()]``. Using plain ``tuple`` as an annotation is equivalent to "
 "using ``tuple[Any, ...]``::"
 msgstr ""
+"為了標示一個元組可以為\\ *任意*\\ 長度，且所有元素皆是相同型別 ``T``，請使用 "
+"``tuple[T, ...]`` 進行標示。為了標示一個空元組，請使用 ``tuple[()]``。單純使"
+"用 ``tuple`` 作為註釋，會與使用 ``tuple[Any, ...]`` 是相等的： ::"
 
 #: ../../library/typing.rst:457
 msgid "The type of class objects"
