From e768ebec3d67fb6dfd66ed6cb41ccb39f634ad19 Mon Sep 17 00:00:00 2001 From: "Raynor@GullU" Date: Thu, 15 Aug 2024 15:39:42 +0800 Subject: [PATCH 01/17] docs(library/pickle.po): editing, up to line 212 --- library/pickle.po | 59 +++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 55 insertions(+), 4 deletions(-) diff --git a/library/pickle.po b/library/pickle.po index 532f1f1884..f73c09164b 100644 --- a/library/pickle.po +++ b/library/pickle.po @@ -2,6 +2,7 @@ # This file is distributed under the same license as the Python package. # # Translators: +# Skylull, 2024 msgid "" msgstr "" "Project-Id-Version: Python 3.12\n" @@ -25,6 +26,14 @@ msgstr ":mod:`!pickle` --- Python 物件序列化" msgid "**Source code:** :source:`Lib/pickle.py`" msgstr "**原始碼：**\\ :source:`Lib/pickle.py`" +# Skylull: 我對 `pickle` 的命名原因進行了簡單的搜尋，只找到一則討論 +# https://stackoverflow.com/questions/27324986/pickles-why-are-they-called- +# that +# 其中表示這名字很可能只是為了隨便找一個p開頭的單字、或原始開發人員的內部玩笑造成的約定俗成。也有人表示醃製黃瓜（pickle- +# ing）的目標就是保存和存放，所以取了這個名字。 +# 無論如何似乎沒有一個定論。 +# 因為不確定是否與醃漬的這個梗有關，我暫時選擇使用 `封裝` 與 `拆封` 作為譯文，大致保存那個把東西處裡後裝起來的感覺但又不至於太奇怪。 +# 唯一需要擔心的是是否有與 `encapsulation` （封裝，網路協定名詞）或 `package`（封包，網路協定名詞）搞混的可能。 #: ../../library/pickle.rst:22 msgid "" "The :mod:`pickle` module implements binary protocols for serializing and de-" @@ -36,10 +45,17 @@ msgid "" "\"serialization\", \"marshalling,\" [#]_ or \"flattening\"; however, to " "avoid confusion, the terms used here are \"pickling\" and \"unpickling\"." msgstr "" +":mod:`pickle` 模組實作的是一個在二進位層級上對 Python 物件進行序列化" +"（serialize）或去序列化（de-serialize）。*\"Pickling\"* 用於專門指摘將一個 " +"Python 物件轉換為一個二進位串流的過程，*\"unpickling\"* 則相反，指的是將一個" +"（來自 :term:`binary file` 或 :term:`bytes-like object` 的）二進位串流轉換回 " +"Python 物件的過程。Pickling（和 unpickling）的過程也可能被稱作 " +"\"serialization\", \"marshalling,\" [#]_ 或 \"flattening\"。不過，為了避免混" +"淆，本文件將統一稱作封裝（pickling）、拆封（unpickling）。" #: ../../library/pickle.rst:33 msgid "The ``pickle`` module **is not secure**. Only unpickle data you trust." -msgstr "" +msgstr "``pickle`` 模組**並不安全**，切記只拆封你信任的資料。" #: ../../library/pickle.rst:35 msgid "" @@ -47,18 +63,22 @@ msgid "" "arbitrary code during unpickling**. Never unpickle data that could have come " "from an untrusted source, or that could have been tampered with." msgstr "" +"pickle 封包是有可能被建立來在拆封的時候**執行任意惡意程式碼**的。絕對不要拆封" +"任何你無法信任其來源、或可能被修改過的 pickle 封包。" #: ../../library/pickle.rst:39 msgid "" "Consider signing data with :mod:`hmac` if you need to ensure that it has not " "been tampered with." -msgstr "" +msgstr "建議你可以使用 :mod:`hmac` 模組來簽署這個封包，以確保其未被修改過。" #: ../../library/pickle.rst:42 msgid "" "Safer serialization formats such as :mod:`json` may be more appropriate if " "you are processing untrusted data. See :ref:`comparison-with-json`." msgstr "" +"如果你在處理不受信任的資料，其他比較安全的序列化格式（例如 :mod:`json`）可能" +"會更適合。請參照 See :ref:`comparison-with-json` 的說明。" #: ../../library/pickle.rst:47 msgid "Relationship to other Python modules" @@ -75,12 +95,15 @@ msgid "" "Python objects. :mod:`marshal` exists primarily to support Python's :file:`." "pyc` files." msgstr "" +"Python 有另一個比較原始的序列化模組叫 :mod:`marshal`，不過其設計目的是為了支" +"援 Python 的預編譯功能 :file:`.pyc` 運作。總地來說，沒事不要用 :mod:" +"`marshal`。" #: ../../library/pickle.rst:57 msgid "" "The :mod:`pickle` module differs from :mod:`marshal` in several significant " "ways:" -msgstr "" +msgstr ":mod:`pickle` 和 :mod:`marshal` 有幾個明顯不同的地方：" #: ../../library/pickle.rst:59 msgid "" @@ -88,6 +111,8 @@ msgid "" "serialized, so that later references to the same object won't be serialized " "again. :mod:`marshal` doesn't do this." msgstr "" +":mod:`pickle` 會記住哪些物件已經被序列化過了，稍後再次參照到這個物件的時候才" +"不會進行重複的序列化。:mod:`marshal` 沒有這個功能。" #: ../../library/pickle.rst:63 msgid "" @@ -101,6 +126,11 @@ msgid "" "Shared objects remain shared, which can be very important for mutable " "objects." msgstr "" +"這對遞迴物件和物件共用都有影響。遞迴物件是指包含自我參照的物件。這些情況在 " +"marshal 模組中不會被處理，若嘗試使用 marshal 處理遞迴物件會導致 Python 直譯器" +"崩潰。物件共用發生在序列化的物件階層中，不同位置對同一物件有多個參照時。:mod:" +"`pickle` 只會儲存這個被參照的物件一次，並確保所有其他參照指向這個主要的版本。" +"共用的物件會保持共用，這對於可變（mutable）物件來說非常重要。" #: ../../library/pickle.rst:72 msgid "" @@ -109,6 +139,9 @@ msgid "" "transparently, however the class definition must be importable and live in " "the same module as when the object was stored." msgstr "" +":mod:`marshal` 無法序列化使用者自訂的類別和的實例。:mod:`pickle` 則可以讓使用" +"者儲存並還原自訂的類別實例，前提是儲存時該類別的定義存在於與要被儲存的物件所" +"在的模組中、且可以被引入（import）。" #: ../../library/pickle.rst:77 msgid "" @@ -122,6 +155,11 @@ msgid "" "differences if your data is crossing that unique breaking change language " "boundary." msgstr "" +":mod:`marshal` 序列化格式無法保證能在不同版本的 Python 之間移植。因為其主要的" +"作用是支援 :file:`.pyc` 檔案的運作，Python 的實作人員會在需要時實作無法前向相" +"容的序列化方式。但只要選擇了相容的 pickle 協定，且處理了 Python 2 和 Python " +"3 之間的資料類型差異，:mod:`pickle` 序列化協定能保證在不同 Python 版本間的相" +"容性。" #: ../../library/pickle.rst:90 msgid "Comparison with ``json``" @@ -132,6 +170,8 @@ msgid "" "There are fundamental differences between the pickle protocols and `JSON " "(JavaScript Object Notation) `_:" msgstr "" +"pickle 協定和 `JSON (JavaScript Object Notation) `_ 有一些" +"根本上的不同：" #: ../../library/pickle.rst:95 msgid "" @@ -139,17 +179,25 @@ msgid "" "of the time it is then encoded to ``utf-8``), while pickle is a binary " "serialization format;" msgstr "" +"JSON 以文字形式作為序列化的輸出（輸出 unicode 文字，但大多數又會被編碼為 " +"``UTF-8``），而 pickle 則是以二進位形式作為序列化的輸出；" #: ../../library/pickle.rst:99 msgid "JSON is human-readable, while pickle is not;" -msgstr "JSON 是人類可讀的，而 pickle 不是；" +msgstr "JSON 是人類可讀的，而 pickle 則無法；" #: ../../library/pickle.rst:101 msgid "" "JSON is interoperable and widely used outside of the Python ecosystem, while " "pickle is Python-specific;" msgstr "" +"JSON 具有高互通性（interoperability）且在 Python 以外的環境也被大量利用，但 " +"pickle 只能在 Python 內使用。" +# Skylull: introspection, introspection facilities +# https://zh.wikipedia.org/wiki/%E5%86%85%E7%9C%81_(%E8%AE%A1%E7%AE%97%E6%9C%BA%E7%A7%91%E5%AD%A6) +# https://book.pythontips.com/en/latest/object_introspection.html +# https://www.geeksforgeeks.org/code-introspection-in-python/ #: ../../library/pickle.rst:104 msgid "" "JSON, by default, can only represent a subset of the Python built-in types, " @@ -158,6 +206,9 @@ msgid "" "introspection facilities; complex cases can be tackled by implementing :ref:" "`specific object APIs `);" msgstr "" +"預設狀態下的 JSON 只能紀錄一小部份的 Python 內建型別，且無法紀錄自訂類別；但" +"透過 Python 的自省功能，pickle 可以紀錄絕大多數的 Python 型別（其他比較複雜的" +"狀況也可以透過實作 :ref:`specific object APIs ` 來解決）；" #: ../../library/pickle.rst:110 msgid "" From 9c6ac561e1d7e1353c9bb47df6a6fa40e5da6b36 Mon Sep 17 00:00:00 2001 From: "Raynor@GullU" Date: Fri, 16 Aug 2024 00:23:06 +0800 Subject: [PATCH 02/17] docs(library/pickle.po): editing, up to line 362 --- library/pickle.po | 36 ++++++++++++++++++++++++++++++++++-- 1 file changed, 34 insertions(+), 2 deletions(-) diff --git a/library/pickle.po b/library/pickle.po index f73c09164b..c91b3e39f8 100644 --- a/library/pickle.po +++ b/library/pickle.po @@ -215,16 +215,20 @@ msgid "" "Unlike pickle, deserializing untrusted JSON does not in itself create an " "arbitrary code execution vulnerability." msgstr "" +"去序列化不安全的 JSON 不會產生任意程式執行的風險，但去序列化不安全的 pickle " +"會。" #: ../../library/pickle.rst:114 msgid "" "The :mod:`json` module: a standard library module allowing JSON " "serialization and deserialization." msgstr "" +":mod:`json` module: 是標準函式庫的一部分，可讓使用者進行 JSON 的序列化與去序" +"列化。" #: ../../library/pickle.rst:121 msgid "Data stream format" -msgstr "" +msgstr "資料串流格式" #: ../../library/pickle.rst:126 msgid "" @@ -234,6 +238,9 @@ msgid "" "that non-Python programs may not be able to reconstruct pickled Python " "objects." msgstr "" +":mod:`pickle` 使用的資料格式是針對 Python 而設計的。好處是他不會受到外部標準" +"（像是 JSON 或 XDR，而 XDR 無法紀錄指標共用）的限制；不過這也代表其他不是 " +"Python 的程式可能無法重建 pickle 封裝的 Python 物件。" #: ../../library/pickle.rst:131 msgid "" @@ -241,6 +248,8 @@ msgid "" "representation. If you need optimal size characteristics, you can " "efficiently :doc:`compress ` pickled data." msgstr "" +"以預設設定來說，:mod:`pickle` 使用相對緊湊的二進位形式來儲存資料。如果你需要" +"盡可能地縮小檔案大小，你可以\\\\ :doc:`壓縮 `\\\\ 封裝的資料。" #: ../../library/pickle.rst:135 msgid "" @@ -248,6 +257,8 @@ msgid "" "generated by :mod:`pickle`. :mod:`pickletools` source code has extensive " "comments about opcodes used by pickle protocols." msgstr "" +":mod:`pickletools` 含有工具可分析 :mod:`pickle` 所產生的資料流。:mod:" +"`pickletools` 的源始碼詳細地記載了所有 pickle 協定的操作碼（opcode）。" #: ../../library/pickle.rst:139 msgid "" @@ -255,18 +266,21 @@ msgid "" "The higher the protocol used, the more recent the version of Python needed " "to read the pickle produced." msgstr "" +"截至目前為止，共有六種不同版本的協定可用於封裝 pickle。數字越大版本代表你需" +"要使用越新的 Python 版本來拆封相應的 pickle 封裝。" #: ../../library/pickle.rst:143 msgid "" "Protocol version 0 is the original \"human-readable\" protocol and is " "backwards compatible with earlier versions of Python." msgstr "" +"版本 0 的協定是最初「人類可讀」的版本，且可以向前支援早期版本的 Python。" #: ../../library/pickle.rst:146 msgid "" "Protocol version 1 is an old binary format which is also compatible with " "earlier versions of Python." -msgstr "" +msgstr "版本 1 的協定使用舊的二進位格式，一樣能向前支援早期版本的 Python。" #: ../../library/pickle.rst:149 msgid "" @@ -274,6 +288,9 @@ msgid "" "efficient pickling of :term:`new-style classes `. Refer " "to :pep:`307` for information about improvements brought by protocol 2." msgstr "" +"版本 2 的協定在 Python 2.3 中初次被引入。其可提供更高效率的 :term:`new-style " +"classes ` 封裝過程。請參閱 :pep:`307` 以了解版本 2 帶來的改" +"進。" #: ../../library/pickle.rst:153 msgid "" @@ -281,6 +298,8 @@ msgid "" "class:`bytes` objects and cannot be unpickled by Python 2.x. This was the " "default protocol in Python 3.0--3.7." msgstr "" +"版本 3 的協定在 Python 3.0 被新增。現在能支援封裝 :class:`bytes` 的物件且無法" +"被 2.x 版本的 Python 拆封。在 3.0～3.7 的 Python 預設使用 3 版協定。" #: ../../library/pickle.rst:157 msgid "" @@ -289,6 +308,9 @@ msgid "" "optimizations. It is the default protocol starting with Python 3.8. Refer " "to :pep:`3154` for information about improvements brought by protocol 4." msgstr "" +"版本 4 的協定在 Python 3.4 被新增。現在能支援超大物件的封裝、更多種型別的物件" +"以及針對部份資料格式的儲存進行最佳化。從 Python 3.8 起，預設使用第 4 版協定。" +"請參閱 :pep:`3154` 以了解第 4 版協定改進的細節。" #: ../../library/pickle.rst:163 msgid "" @@ -310,6 +332,12 @@ msgid "" "database. The :mod:`shelve` module provides a simple interface to pickle " "and unpickle objects on DBM-style database files." msgstr "" +"資料序列化是一個比資料持久化更早期的概念；雖然 :mod:`pickle` 可以讀寫檔案物" +"件，但它並不處理命名持久物件的問題，也不處理對持久物件並行存取，一個更棘手的" +"問題。:mod:`pickle` 模組可以將複雜物件轉換成位元組串流，也可以將位元組串流轉" +"換回具有相同原始內部結構的物件。對這些位元組串流最明顯的處理方式大概是將它們" +"寫入檔案中，但也可能將它們透過網路傳送或儲存在一個資料庫中。:mod:`shelve` 模" +"組提供了一個簡單的介面來在 DBM 風格的資料庫檔案中進行物件的封裝和拆封的操作。" #: ../../library/pickle.rst:181 msgid "Module Interface" @@ -323,6 +351,10 @@ msgid "" "de-serialization, you can create a :class:`Pickler` or an :class:`Unpickler` " "object, respectively." msgstr "" +"想要序列化一個物件，你只需要呼叫 :func:`dumps` 函數。而當你想要去序列化一個資" +"料流時，你只需要呼叫 :func:`loads` 即可。不過，若你希望能各自對序列化和去序列" +"化的過程中有更多的掌控度，你可以自訂一個 :class:`Pickler` 或 :class:" +"`Unpickler` 物件。" #: ../../library/pickle.rst:188 msgid "The :mod:`pickle` module provides the following constants:" From 8b9479ffbde0a4adf35ec526c7a1cb1e78289b2f Mon Sep 17 00:00:00 2001 From: "Raynor@GullU" Date: Mon, 19 Aug 2024 17:54:46 +0800 Subject: [PATCH 03/17] docs(library/pickle.po): editing, up to line 375. --- library/pickle.po | 3092 ++++++++++++++++++++++----------------------- 1 file changed, 1542 insertions(+), 1550 deletions(-) diff --git a/library/pickle.po b/library/pickle.po index c91b3e39f8..95f0a47a95 100644 --- a/library/pickle.po +++ b/library/pickle.po @@ -1,1550 +1,1542 @@ -# Copyright (C) 2001-2024, Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Skylull, 2024 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.12\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-05-09 00:03+0000\n" -"PO-Revision-Date: 2018-05-23 16:07+0000\n" -"Last-Translator: Adrian Liaw \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" -"Plural-Forms: nplurals=1; plural=0;\n" - -#: ../../library/pickle.rst:2 -msgid ":mod:`!pickle` --- Python object serialization" -msgstr ":mod:`!pickle` --- Python 物件序列化" - -#: ../../library/pickle.rst:10 -msgid "**Source code:** :source:`Lib/pickle.py`" -msgstr "**原始碼：**\\ :source:`Lib/pickle.py`" - -# Skylull: 我對 `pickle` 的命名原因進行了簡單的搜尋，只找到一則討論 -# https://stackoverflow.com/questions/27324986/pickles-why-are-they-called- -# that -# 其中表示這名字很可能只是為了隨便找一個p開頭的單字、或原始開發人員的內部玩笑造成的約定俗成。也有人表示醃製黃瓜（pickle- -# ing）的目標就是保存和存放，所以取了這個名字。 -# 無論如何似乎沒有一個定論。 -# 因為不確定是否與醃漬的這個梗有關，我暫時選擇使用 `封裝` 與 `拆封` 作為譯文，大致保存那個把東西處裡後裝起來的感覺但又不至於太奇怪。 -# 唯一需要擔心的是是否有與 `encapsulation` （封裝，網路協定名詞）或 `package`（封包，網路協定名詞）搞混的可能。 -#: ../../library/pickle.rst:22 -msgid "" -"The :mod:`pickle` module implements binary protocols for serializing and de-" -"serializing a Python object structure. *\"Pickling\"* is the process " -"whereby a Python object hierarchy is converted into a byte stream, and " -"*\"unpickling\"* is the inverse operation, whereby a byte stream (from a :" -"term:`binary file` or :term:`bytes-like object`) is converted back into an " -"object hierarchy. Pickling (and unpickling) is alternatively known as " -"\"serialization\", \"marshalling,\" [#]_ or \"flattening\"; however, to " -"avoid confusion, the terms used here are \"pickling\" and \"unpickling\"." -msgstr "" -":mod:`pickle` 模組實作的是一個在二進位層級上對 Python 物件進行序列化" -"（serialize）或去序列化（de-serialize）。*\"Pickling\"* 用於專門指摘將一個 " -"Python 物件轉換為一個二進位串流的過程，*\"unpickling\"* 則相反，指的是將一個" -"（來自 :term:`binary file` 或 :term:`bytes-like object` 的）二進位串流轉換回 " -"Python 物件的過程。Pickling（和 unpickling）的過程也可能被稱作 " -"\"serialization\", \"marshalling,\" [#]_ 或 \"flattening\"。不過，為了避免混" -"淆，本文件將統一稱作封裝（pickling）、拆封（unpickling）。" - -#: ../../library/pickle.rst:33 -msgid "The ``pickle`` module **is not secure**. Only unpickle data you trust." -msgstr "``pickle`` 模組**並不安全**，切記只拆封你信任的資料。" - -#: ../../library/pickle.rst:35 -msgid "" -"It is possible to construct malicious pickle data which will **execute " -"arbitrary code during unpickling**. Never unpickle data that could have come " -"from an untrusted source, or that could have been tampered with." -msgstr "" -"pickle 封包是有可能被建立來在拆封的時候**執行任意惡意程式碼**的。絕對不要拆封" -"任何你無法信任其來源、或可能被修改過的 pickle 封包。" - -#: ../../library/pickle.rst:39 -msgid "" -"Consider signing data with :mod:`hmac` if you need to ensure that it has not " -"been tampered with." -msgstr "建議你可以使用 :mod:`hmac` 模組來簽署這個封包，以確保其未被修改過。" - -#: ../../library/pickle.rst:42 -msgid "" -"Safer serialization formats such as :mod:`json` may be more appropriate if " -"you are processing untrusted data. See :ref:`comparison-with-json`." -msgstr "" -"如果你在處理不受信任的資料，其他比較安全的序列化格式（例如 :mod:`json`）可能" -"會更適合。請參照 See :ref:`comparison-with-json` 的說明。" - -#: ../../library/pickle.rst:47 -msgid "Relationship to other Python modules" -msgstr "和其他 Python 模組的關係" - -#: ../../library/pickle.rst:50 -msgid "Comparison with ``marshal``" -msgstr "和 ``marshal`` 的比較" - -#: ../../library/pickle.rst:52 -msgid "" -"Python has a more primitive serialization module called :mod:`marshal`, but " -"in general :mod:`pickle` should always be the preferred way to serialize " -"Python objects. :mod:`marshal` exists primarily to support Python's :file:`." -"pyc` files." -msgstr "" -"Python 有另一個比較原始的序列化模組叫 :mod:`marshal`，不過其設計目的是為了支" -"援 Python 的預編譯功能 :file:`.pyc` 運作。總地來說，沒事不要用 :mod:" -"`marshal`。" - -#: ../../library/pickle.rst:57 -msgid "" -"The :mod:`pickle` module differs from :mod:`marshal` in several significant " -"ways:" -msgstr ":mod:`pickle` 和 :mod:`marshal` 有幾個明顯不同的地方：" - -#: ../../library/pickle.rst:59 -msgid "" -"The :mod:`pickle` module keeps track of the objects it has already " -"serialized, so that later references to the same object won't be serialized " -"again. :mod:`marshal` doesn't do this." -msgstr "" -":mod:`pickle` 會記住哪些物件已經被序列化過了，稍後再次參照到這個物件的時候才" -"不會進行重複的序列化。:mod:`marshal` 沒有這個功能。" - -#: ../../library/pickle.rst:63 -msgid "" -"This has implications both for recursive objects and object sharing. " -"Recursive objects are objects that contain references to themselves. These " -"are not handled by marshal, and in fact, attempting to marshal recursive " -"objects will crash your Python interpreter. Object sharing happens when " -"there are multiple references to the same object in different places in the " -"object hierarchy being serialized. :mod:`pickle` stores such objects only " -"once, and ensures that all other references point to the master copy. " -"Shared objects remain shared, which can be very important for mutable " -"objects." -msgstr "" -"這對遞迴物件和物件共用都有影響。遞迴物件是指包含自我參照的物件。這些情況在 " -"marshal 模組中不會被處理，若嘗試使用 marshal 處理遞迴物件會導致 Python 直譯器" -"崩潰。物件共用發生在序列化的物件階層中，不同位置對同一物件有多個參照時。:mod:" -"`pickle` 只會儲存這個被參照的物件一次，並確保所有其他參照指向這個主要的版本。" -"共用的物件會保持共用，這對於可變（mutable）物件來說非常重要。" - -#: ../../library/pickle.rst:72 -msgid "" -":mod:`marshal` cannot be used to serialize user-defined classes and their " -"instances. :mod:`pickle` can save and restore class instances " -"transparently, however the class definition must be importable and live in " -"the same module as when the object was stored." -msgstr "" -":mod:`marshal` 無法序列化使用者自訂的類別和的實例。:mod:`pickle` 則可以讓使用" -"者儲存並還原自訂的類別實例，前提是儲存時該類別的定義存在於與要被儲存的物件所" -"在的模組中、且可以被引入（import）。" - -#: ../../library/pickle.rst:77 -msgid "" -"The :mod:`marshal` serialization format is not guaranteed to be portable " -"across Python versions. Because its primary job in life is to support :file:" -"`.pyc` files, the Python implementers reserve the right to change the " -"serialization format in non-backwards compatible ways should the need arise. " -"The :mod:`pickle` serialization format is guaranteed to be backwards " -"compatible across Python releases provided a compatible pickle protocol is " -"chosen and pickling and unpickling code deals with Python 2 to Python 3 type " -"differences if your data is crossing that unique breaking change language " -"boundary." -msgstr "" -":mod:`marshal` 序列化格式無法保證能在不同版本的 Python 之間移植。因為其主要的" -"作用是支援 :file:`.pyc` 檔案的運作，Python 的實作人員會在需要時實作無法前向相" -"容的序列化方式。但只要選擇了相容的 pickle 協定，且處理了 Python 2 和 Python " -"3 之間的資料類型差異，:mod:`pickle` 序列化協定能保證在不同 Python 版本間的相" -"容性。" - -#: ../../library/pickle.rst:90 -msgid "Comparison with ``json``" -msgstr "和 ``json`` 的比較" - -#: ../../library/pickle.rst:92 -msgid "" -"There are fundamental differences between the pickle protocols and `JSON " -"(JavaScript Object Notation) `_:" -msgstr "" -"pickle 協定和 `JSON (JavaScript Object Notation) `_ 有一些" -"根本上的不同：" - -#: ../../library/pickle.rst:95 -msgid "" -"JSON is a text serialization format (it outputs unicode text, although most " -"of the time it is then encoded to ``utf-8``), while pickle is a binary " -"serialization format;" -msgstr "" -"JSON 以文字形式作為序列化的輸出（輸出 unicode 文字，但大多數又會被編碼為 " -"``UTF-8``），而 pickle 則是以二進位形式作為序列化的輸出；" - -#: ../../library/pickle.rst:99 -msgid "JSON is human-readable, while pickle is not;" -msgstr "JSON 是人類可讀的，而 pickle 則無法；" - -#: ../../library/pickle.rst:101 -msgid "" -"JSON is interoperable and widely used outside of the Python ecosystem, while " -"pickle is Python-specific;" -msgstr "" -"JSON 具有高互通性（interoperability）且在 Python 以外的環境也被大量利用，但 " -"pickle 只能在 Python 內使用。" - -# Skylull: introspection, introspection facilities -# https://zh.wikipedia.org/wiki/%E5%86%85%E7%9C%81_(%E8%AE%A1%E7%AE%97%E6%9C%BA%E7%A7%91%E5%AD%A6) -# https://book.pythontips.com/en/latest/object_introspection.html -# https://www.geeksforgeeks.org/code-introspection-in-python/ -#: ../../library/pickle.rst:104 -msgid "" -"JSON, by default, can only represent a subset of the Python built-in types, " -"and no custom classes; pickle can represent an extremely large number of " -"Python types (many of them automatically, by clever usage of Python's " -"introspection facilities; complex cases can be tackled by implementing :ref:" -"`specific object APIs `);" -msgstr "" -"預設狀態下的 JSON 只能紀錄一小部份的 Python 內建型別，且無法紀錄自訂類別；但" -"透過 Python 的自省功能，pickle 可以紀錄絕大多數的 Python 型別（其他比較複雜的" -"狀況也可以透過實作 :ref:`specific object APIs ` 來解決）；" - -#: ../../library/pickle.rst:110 -msgid "" -"Unlike pickle, deserializing untrusted JSON does not in itself create an " -"arbitrary code execution vulnerability." -msgstr "" -"去序列化不安全的 JSON 不會產生任意程式執行的風險，但去序列化不安全的 pickle " -"會。" - -#: ../../library/pickle.rst:114 -msgid "" -"The :mod:`json` module: a standard library module allowing JSON " -"serialization and deserialization." -msgstr "" -":mod:`json` module: 是標準函式庫的一部分，可讓使用者進行 JSON 的序列化與去序" -"列化。" - -#: ../../library/pickle.rst:121 -msgid "Data stream format" -msgstr "資料串流格式" - -#: ../../library/pickle.rst:126 -msgid "" -"The data format used by :mod:`pickle` is Python-specific. This has the " -"advantage that there are no restrictions imposed by external standards such " -"as JSON or XDR (which can't represent pointer sharing); however it means " -"that non-Python programs may not be able to reconstruct pickled Python " -"objects." -msgstr "" -":mod:`pickle` 使用的資料格式是針對 Python 而設計的。好處是他不會受到外部標準" -"（像是 JSON 或 XDR，而 XDR 無法紀錄指標共用）的限制；不過這也代表其他不是 " -"Python 的程式可能無法重建 pickle 封裝的 Python 物件。" - -#: ../../library/pickle.rst:131 -msgid "" -"By default, the :mod:`pickle` data format uses a relatively compact binary " -"representation. If you need optimal size characteristics, you can " -"efficiently :doc:`compress ` pickled data." -msgstr "" -"以預設設定來說，:mod:`pickle` 使用相對緊湊的二進位形式來儲存資料。如果你需要" -"盡可能地縮小檔案大小，你可以\\\\ :doc:`壓縮 `\\\\ 封裝的資料。" - -#: ../../library/pickle.rst:135 -msgid "" -"The module :mod:`pickletools` contains tools for analyzing data streams " -"generated by :mod:`pickle`. :mod:`pickletools` source code has extensive " -"comments about opcodes used by pickle protocols." -msgstr "" -":mod:`pickletools` 含有工具可分析 :mod:`pickle` 所產生的資料流。:mod:" -"`pickletools` 的源始碼詳細地記載了所有 pickle 協定的操作碼（opcode）。" - -#: ../../library/pickle.rst:139 -msgid "" -"There are currently 6 different protocols which can be used for pickling. " -"The higher the protocol used, the more recent the version of Python needed " -"to read the pickle produced." -msgstr "" -"截至目前為止，共有六種不同版本的協定可用於封裝 pickle。數字越大版本代表你需" -"要使用越新的 Python 版本來拆封相應的 pickle 封裝。" - -#: ../../library/pickle.rst:143 -msgid "" -"Protocol version 0 is the original \"human-readable\" protocol and is " -"backwards compatible with earlier versions of Python." -msgstr "" -"版本 0 的協定是最初「人類可讀」的版本，且可以向前支援早期版本的 Python。" - -#: ../../library/pickle.rst:146 -msgid "" -"Protocol version 1 is an old binary format which is also compatible with " -"earlier versions of Python." -msgstr "版本 1 的協定使用舊的二進位格式，一樣能向前支援早期版本的 Python。" - -#: ../../library/pickle.rst:149 -msgid "" -"Protocol version 2 was introduced in Python 2.3. It provides much more " -"efficient pickling of :term:`new-style classes `. Refer " -"to :pep:`307` for information about improvements brought by protocol 2." -msgstr "" -"版本 2 的協定在 Python 2.3 中初次被引入。其可提供更高效率的 :term:`new-style " -"classes ` 封裝過程。請參閱 :pep:`307` 以了解版本 2 帶來的改" -"進。" - -#: ../../library/pickle.rst:153 -msgid "" -"Protocol version 3 was added in Python 3.0. It has explicit support for :" -"class:`bytes` objects and cannot be unpickled by Python 2.x. This was the " -"default protocol in Python 3.0--3.7." -msgstr "" -"版本 3 的協定在 Python 3.0 被新增。現在能支援封裝 :class:`bytes` 的物件且無法" -"被 2.x 版本的 Python 拆封。在 3.0～3.7 的 Python 預設使用 3 版協定。" - -#: ../../library/pickle.rst:157 -msgid "" -"Protocol version 4 was added in Python 3.4. It adds support for very large " -"objects, pickling more kinds of objects, and some data format " -"optimizations. It is the default protocol starting with Python 3.8. Refer " -"to :pep:`3154` for information about improvements brought by protocol 4." -msgstr "" -"版本 4 的協定在 Python 3.4 被新增。現在能支援超大物件的封裝、更多種型別的物件" -"以及針對部份資料格式的儲存進行最佳化。從 Python 3.8 起，預設使用第 4 版協定。" -"請參閱 :pep:`3154` 以了解第 4 版協定改進的細節。" - -#: ../../library/pickle.rst:163 -msgid "" -"Protocol version 5 was added in Python 3.8. It adds support for out-of-band " -"data and speedup for in-band data. Refer to :pep:`574` for information " -"about improvements brought by protocol 5." -msgstr "" - -#: ../../library/pickle.rst:168 -msgid "" -"Serialization is a more primitive notion than persistence; although :mod:" -"`pickle` reads and writes file objects, it does not handle the issue of " -"naming persistent objects, nor the (even more complicated) issue of " -"concurrent access to persistent objects. The :mod:`pickle` module can " -"transform a complex object into a byte stream and it can transform the byte " -"stream into an object with the same internal structure. Perhaps the most " -"obvious thing to do with these byte streams is to write them onto a file, " -"but it is also conceivable to send them across a network or store them in a " -"database. The :mod:`shelve` module provides a simple interface to pickle " -"and unpickle objects on DBM-style database files." -msgstr "" -"資料序列化是一個比資料持久化更早期的概念；雖然 :mod:`pickle` 可以讀寫檔案物" -"件，但它並不處理命名持久物件的問題，也不處理對持久物件並行存取，一個更棘手的" -"問題。:mod:`pickle` 模組可以將複雜物件轉換成位元組串流，也可以將位元組串流轉" -"換回具有相同原始內部結構的物件。對這些位元組串流最明顯的處理方式大概是將它們" -"寫入檔案中，但也可能將它們透過網路傳送或儲存在一個資料庫中。:mod:`shelve` 模" -"組提供了一個簡單的介面來在 DBM 風格的資料庫檔案中進行物件的封裝和拆封的操作。" - -#: ../../library/pickle.rst:181 -msgid "Module Interface" -msgstr "模組介面" - -#: ../../library/pickle.rst:183 -msgid "" -"To serialize an object hierarchy, you simply call the :func:`dumps` " -"function. Similarly, to de-serialize a data stream, you call the :func:" -"`loads` function. However, if you want more control over serialization and " -"de-serialization, you can create a :class:`Pickler` or an :class:`Unpickler` " -"object, respectively." -msgstr "" -"想要序列化一個物件，你只需要呼叫 :func:`dumps` 函數。而當你想要去序列化一個資" -"料流時，你只需要呼叫 :func:`loads` 即可。不過，若你希望能各自對序列化和去序列" -"化的過程中有更多的掌控度，你可以自訂一個 :class:`Pickler` 或 :class:" -"`Unpickler` 物件。" - -#: ../../library/pickle.rst:188 -msgid "The :mod:`pickle` module provides the following constants:" -msgstr ":mod:`pickle` 模組提供以下常數：" - -#: ../../library/pickle.rst:193 -msgid "" -"An integer, the highest :ref:`protocol version ` " -"available. This value can be passed as a *protocol* value to functions :" -"func:`dump` and :func:`dumps` as well as the :class:`Pickler` constructor." -msgstr "" - -#: ../../library/pickle.rst:200 -msgid "" -"An integer, the default :ref:`protocol version ` used for " -"pickling. May be less than :data:`HIGHEST_PROTOCOL`. Currently the default " -"protocol is 4, first introduced in Python 3.4 and incompatible with previous " -"versions." -msgstr "" - -#: ../../library/pickle.rst:207 -msgid "The default protocol is 3." -msgstr "預設協定為 3。" - -#: ../../library/pickle.rst:211 -msgid "The default protocol is 4." -msgstr "預設協定為 4。" - -#: ../../library/pickle.rst:213 -msgid "" -"The :mod:`pickle` module provides the following functions to make the " -"pickling process more convenient:" -msgstr "" - -#: ../../library/pickle.rst:218 -msgid "" -"Write the pickled representation of the object *obj* to the open :term:`file " -"object` *file*. This is equivalent to ``Pickler(file, protocol).dump(obj)``." -msgstr "" - -#: ../../library/pickle.rst:222 -msgid "" -"Arguments *file*, *protocol*, *fix_imports* and *buffer_callback* have the " -"same meaning as in the :class:`Pickler` constructor." -msgstr "" - -#: ../../library/pickle.rst:225 ../../library/pickle.rst:236 -#: ../../library/pickle.rst:328 -msgid "The *buffer_callback* argument was added." -msgstr "新增 *buffer_callback* 引數。" - -#: ../../library/pickle.rst:230 -msgid "" -"Return the pickled representation of the object *obj* as a :class:`bytes` " -"object, instead of writing it to a file." -msgstr "" - -#: ../../library/pickle.rst:233 -msgid "" -"Arguments *protocol*, *fix_imports* and *buffer_callback* have the same " -"meaning as in the :class:`Pickler` constructor." -msgstr "" - -#: ../../library/pickle.rst:241 -msgid "" -"Read the pickled representation of an object from the open :term:`file " -"object` *file* and return the reconstituted object hierarchy specified " -"therein. This is equivalent to ``Unpickler(file).load()``." -msgstr "" - -#: ../../library/pickle.rst:245 ../../library/pickle.rst:260 -msgid "" -"The protocol version of the pickle is detected automatically, so no protocol " -"argument is needed. Bytes past the pickled representation of the object are " -"ignored." -msgstr "" - -#: ../../library/pickle.rst:249 -msgid "" -"Arguments *file*, *fix_imports*, *encoding*, *errors*, *strict* and " -"*buffers* have the same meaning as in the :class:`Unpickler` constructor." -msgstr "" - -#: ../../library/pickle.rst:252 ../../library/pickle.rst:267 -#: ../../library/pickle.rst:429 -msgid "The *buffers* argument was added." -msgstr "新增 *buffer* 引數。" - -#: ../../library/pickle.rst:257 -msgid "" -"Return the reconstituted object hierarchy of the pickled representation " -"*data* of an object. *data* must be a :term:`bytes-like object`." -msgstr "" - -#: ../../library/pickle.rst:264 -msgid "" -"Arguments *fix_imports*, *encoding*, *errors*, *strict* and *buffers* have " -"the same meaning as in the :class:`Unpickler` constructor." -msgstr "" - -#: ../../library/pickle.rst:271 -msgid "The :mod:`pickle` module defines three exceptions:" -msgstr "" - -#: ../../library/pickle.rst:275 -msgid "" -"Common base class for the other pickling exceptions. It inherits from :exc:" -"`Exception`." -msgstr "" - -#: ../../library/pickle.rst:280 -msgid "" -"Error raised when an unpicklable object is encountered by :class:`Pickler`. " -"It inherits from :exc:`PickleError`." -msgstr "" - -#: ../../library/pickle.rst:283 -msgid "" -"Refer to :ref:`pickle-picklable` to learn what kinds of objects can be " -"pickled." -msgstr "" - -#: ../../library/pickle.rst:288 -msgid "" -"Error raised when there is a problem unpickling an object, such as a data " -"corruption or a security violation. It inherits from :exc:`PickleError`." -msgstr "" - -#: ../../library/pickle.rst:291 -msgid "" -"Note that other exceptions may also be raised during unpickling, including " -"(but not necessarily limited to) AttributeError, EOFError, ImportError, and " -"IndexError." -msgstr "" - -#: ../../library/pickle.rst:296 -msgid "" -"The :mod:`pickle` module exports three classes, :class:`Pickler`, :class:" -"`Unpickler` and :class:`PickleBuffer`:" -msgstr "" - -#: ../../library/pickle.rst:301 -msgid "This takes a binary file for writing a pickle data stream." -msgstr "" - -#: ../../library/pickle.rst:303 -msgid "" -"The optional *protocol* argument, an integer, tells the pickler to use the " -"given protocol; supported protocols are 0 to :data:`HIGHEST_PROTOCOL`. If " -"not specified, the default is :data:`DEFAULT_PROTOCOL`. If a negative " -"number is specified, :data:`HIGHEST_PROTOCOL` is selected." -msgstr "" - -#: ../../library/pickle.rst:308 -msgid "" -"The *file* argument must have a write() method that accepts a single bytes " -"argument. It can thus be an on-disk file opened for binary writing, an :" -"class:`io.BytesIO` instance, or any other custom object that meets this " -"interface." -msgstr "" - -#: ../../library/pickle.rst:313 -msgid "" -"If *fix_imports* is true and *protocol* is less than 3, pickle will try to " -"map the new Python 3 names to the old module names used in Python 2, so that " -"the pickle data stream is readable with Python 2." -msgstr "" - -#: ../../library/pickle.rst:317 -msgid "" -"If *buffer_callback* is ``None`` (the default), buffer views are serialized " -"into *file* as part of the pickle stream." -msgstr "" - -#: ../../library/pickle.rst:320 -msgid "" -"If *buffer_callback* is not ``None``, then it can be called any number of " -"times with a buffer view. If the callback returns a false value (such as " -"``None``), the given buffer is :ref:`out-of-band `; otherwise " -"the buffer is serialized in-band, i.e. inside the pickle stream." -msgstr "" - -#: ../../library/pickle.rst:325 -msgid "" -"It is an error if *buffer_callback* is not ``None`` and *protocol* is " -"``None`` or smaller than 5." -msgstr "" - -#: ../../library/pickle.rst:333 -msgid "" -"Write the pickled representation of *obj* to the open file object given in " -"the constructor." -msgstr "" - -#: ../../library/pickle.rst:338 -msgid "Do nothing by default. This exists so a subclass can override it." -msgstr "" - -#: ../../library/pickle.rst:340 -msgid "" -"If :meth:`persistent_id` returns ``None``, *obj* is pickled as usual. Any " -"other value causes :class:`Pickler` to emit the returned value as a " -"persistent ID for *obj*. The meaning of this persistent ID should be " -"defined by :meth:`Unpickler.persistent_load`. Note that the value returned " -"by :meth:`persistent_id` cannot itself have a persistent ID." -msgstr "" - -#: ../../library/pickle.rst:346 ../../library/pickle.rst:447 -msgid "See :ref:`pickle-persistent` for details and examples of uses." -msgstr "關於細節與用法範例請見 :ref:`pickle-persistent`。" - -#: ../../library/pickle.rst:350 -msgid "" -"A pickler object's dispatch table is a registry of *reduction functions* of " -"the kind which can be declared using :func:`copyreg.pickle`. It is a " -"mapping whose keys are classes and whose values are reduction functions. A " -"reduction function takes a single argument of the associated class and " -"should conform to the same interface as a :meth:`~object.__reduce__` method." -msgstr "" - -#: ../../library/pickle.rst:358 -msgid "" -"By default, a pickler object will not have a :attr:`dispatch_table` " -"attribute, and it will instead use the global dispatch table managed by the :" -"mod:`copyreg` module. However, to customize the pickling for a specific " -"pickler object one can set the :attr:`dispatch_table` attribute to a dict-" -"like object. Alternatively, if a subclass of :class:`Pickler` has a :attr:" -"`dispatch_table` attribute then this will be used as the default dispatch " -"table for instances of that class." -msgstr "" - -#: ../../library/pickle.rst:367 -msgid "See :ref:`pickle-dispatch` for usage examples." -msgstr "關於用法範例請見 :ref:`pickle-dispatch`。" - -#: ../../library/pickle.rst:373 -msgid "" -"Special reducer that can be defined in :class:`Pickler` subclasses. This " -"method has priority over any reducer in the :attr:`dispatch_table`. It " -"should conform to the same interface as a :meth:`~object.__reduce__` method, " -"and can optionally return :data:`NotImplemented` to fallback on :attr:" -"`dispatch_table`-registered reducers to pickle ``obj``." -msgstr "" - -#: ../../library/pickle.rst:379 -msgid "For a detailed example, see :ref:`reducer_override`." -msgstr "" - -#: ../../library/pickle.rst:385 -msgid "" -"Deprecated. Enable fast mode if set to a true value. The fast mode disables " -"the usage of memo, therefore speeding the pickling process by not generating " -"superfluous PUT opcodes. It should not be used with self-referential " -"objects, doing otherwise will cause :class:`Pickler` to recurse infinitely." -msgstr "" - -#: ../../library/pickle.rst:391 -msgid "Use :func:`pickletools.optimize` if you need more compact pickles." -msgstr "" - -#: ../../library/pickle.rst:396 -msgid "This takes a binary file for reading a pickle data stream." -msgstr "" - -#: ../../library/pickle.rst:398 -msgid "" -"The protocol version of the pickle is detected automatically, so no protocol " -"argument is needed." -msgstr "" - -#: ../../library/pickle.rst:401 -msgid "" -"The argument *file* must have three methods, a read() method that takes an " -"integer argument, a readinto() method that takes a buffer argument and a " -"readline() method that requires no arguments, as in the :class:`io." -"BufferedIOBase` interface. Thus *file* can be an on-disk file opened for " -"binary reading, an :class:`io.BytesIO` object, or any other custom object " -"that meets this interface." -msgstr "" - -#: ../../library/pickle.rst:408 -msgid "" -"The optional arguments *fix_imports*, *encoding* and *errors* are used to " -"control compatibility support for pickle stream generated by Python 2. If " -"*fix_imports* is true, pickle will try to map the old Python 2 names to the " -"new names used in Python 3. The *encoding* and *errors* tell pickle how to " -"decode 8-bit string instances pickled by Python 2; these default to 'ASCII' " -"and 'strict', respectively. The *encoding* can be 'bytes' to read these 8-" -"bit string instances as bytes objects. Using ``encoding='latin1'`` is " -"required for unpickling NumPy arrays and instances of :class:`~datetime." -"datetime`, :class:`~datetime.date` and :class:`~datetime.time` pickled by " -"Python 2." -msgstr "" - -#: ../../library/pickle.rst:419 -msgid "" -"If *buffers* is ``None`` (the default), then all data necessary for " -"deserialization must be contained in the pickle stream. This means that the " -"*buffer_callback* argument was ``None`` when a :class:`Pickler` was " -"instantiated (or when :func:`dump` or :func:`dumps` was called)." -msgstr "" - -#: ../../library/pickle.rst:424 -msgid "" -"If *buffers* is not ``None``, it should be an iterable of buffer-enabled " -"objects that is consumed each time the pickle stream references an :ref:`out-" -"of-band ` buffer view. Such buffers have been given in order to " -"the *buffer_callback* of a Pickler object." -msgstr "" - -#: ../../library/pickle.rst:434 -msgid "" -"Read the pickled representation of an object from the open file object given " -"in the constructor, and return the reconstituted object hierarchy specified " -"therein. Bytes past the pickled representation of the object are ignored." -msgstr "" - -#: ../../library/pickle.rst:441 -msgid "Raise an :exc:`UnpicklingError` by default." -msgstr "" - -#: ../../library/pickle.rst:443 -msgid "" -"If defined, :meth:`persistent_load` should return the object specified by " -"the persistent ID *pid*. If an invalid persistent ID is encountered, an :" -"exc:`UnpicklingError` should be raised." -msgstr "" - -#: ../../library/pickle.rst:451 -msgid "" -"Import *module* if necessary and return the object called *name* from it, " -"where the *module* and *name* arguments are :class:`str` objects. Note, " -"unlike its name suggests, :meth:`find_class` is also used for finding " -"functions." -msgstr "" - -#: ../../library/pickle.rst:456 -msgid "" -"Subclasses may override this to gain control over what type of objects and " -"how they can be loaded, potentially reducing security risks. Refer to :ref:" -"`pickle-restrict` for details." -msgstr "" - -#: ../../library/pickle.rst:460 -msgid "" -"Raises an :ref:`auditing event ` ``pickle.find_class`` with " -"arguments ``module``, ``name``." -msgstr "" -"引發一個附帶引數 ``module``、``name`` 的\\ :ref:`稽核事件 ` " -"``pickle.find_class``。" - -#: ../../library/pickle.rst:464 -msgid "" -"A wrapper for a buffer representing picklable data. *buffer* must be a :ref:" -"`buffer-providing ` object, such as a :term:`bytes-like " -"object` or a N-dimensional array." -msgstr "" - -#: ../../library/pickle.rst:468 -msgid "" -":class:`PickleBuffer` is itself a buffer provider, therefore it is possible " -"to pass it to other APIs expecting a buffer-providing object, such as :class:" -"`memoryview`." -msgstr "" - -#: ../../library/pickle.rst:472 -msgid "" -":class:`PickleBuffer` objects can only be serialized using pickle protocol 5 " -"or higher. They are eligible for :ref:`out-of-band serialization `." -msgstr "" - -#: ../../library/pickle.rst:480 -msgid "" -"Return a :class:`memoryview` of the memory area underlying this buffer. The " -"returned object is a one-dimensional, C-contiguous memoryview with format " -"``B`` (unsigned bytes). :exc:`BufferError` is raised if the buffer is " -"neither C- nor Fortran-contiguous." -msgstr "" - -#: ../../library/pickle.rst:487 -msgid "Release the underlying buffer exposed by the PickleBuffer object." -msgstr "" - -#: ../../library/pickle.rst:493 -msgid "What can be pickled and unpickled?" -msgstr "" - -#: ../../library/pickle.rst:495 -msgid "The following types can be pickled:" -msgstr "" - -#: ../../library/pickle.rst:497 -msgid "" -"built-in constants (``None``, ``True``, ``False``, ``Ellipsis``, and :data:" -"`NotImplemented`);" -msgstr "" - -#: ../../library/pickle.rst:500 -msgid "integers, floating-point numbers, complex numbers;" -msgstr "" - -#: ../../library/pickle.rst:502 -msgid "strings, bytes, bytearrays;" -msgstr "" - -#: ../../library/pickle.rst:504 -msgid "" -"tuples, lists, sets, and dictionaries containing only picklable objects;" -msgstr "" - -#: ../../library/pickle.rst:506 -msgid "" -"functions (built-in and user-defined) accessible from the top level of a " -"module (using :keyword:`def`, not :keyword:`lambda`);" -msgstr "" - -#: ../../library/pickle.rst:509 -msgid "classes accessible from the top level of a module;" -msgstr "" - -#: ../../library/pickle.rst:511 -msgid "" -"instances of such classes whose the result of calling :meth:`~object." -"__getstate__` is picklable (see section :ref:`pickle-inst` for details)." -msgstr "" - -#: ../../library/pickle.rst:514 -msgid "" -"Attempts to pickle unpicklable objects will raise the :exc:`PicklingError` " -"exception; when this happens, an unspecified number of bytes may have " -"already been written to the underlying file. Trying to pickle a highly " -"recursive data structure may exceed the maximum recursion depth, a :exc:" -"`RecursionError` will be raised in this case. You can carefully raise this " -"limit with :func:`sys.setrecursionlimit`." -msgstr "" - -#: ../../library/pickle.rst:521 -msgid "" -"Note that functions (built-in and user-defined) are pickled by fully :term:" -"`qualified name`, not by value. [#]_ This means that only the function name " -"is pickled, along with the name of the containing module and classes. " -"Neither the function's code, nor any of its function attributes are " -"pickled. Thus the defining module must be importable in the unpickling " -"environment, and the module must contain the named object, otherwise an " -"exception will be raised. [#]_" -msgstr "" - -#: ../../library/pickle.rst:528 -msgid "" -"Similarly, classes are pickled by fully qualified name, so the same " -"restrictions in the unpickling environment apply. Note that none of the " -"class's code or data is pickled, so in the following example the class " -"attribute ``attr`` is not restored in the unpickling environment::" -msgstr "" - -#: ../../library/pickle.rst:538 -msgid "" -"These restrictions are why picklable functions and classes must be defined " -"at the top level of a module." -msgstr "" - -#: ../../library/pickle.rst:541 -msgid "" -"Similarly, when class instances are pickled, their class's code and data are " -"not pickled along with them. Only the instance data are pickled. This is " -"done on purpose, so you can fix bugs in a class or add methods to the class " -"and still load objects that were created with an earlier version of the " -"class. If you plan to have long-lived objects that will see many versions " -"of a class, it may be worthwhile to put a version number in the objects so " -"that suitable conversions can be made by the class's :meth:`~object." -"__setstate__` method." -msgstr "" - -#: ../../library/pickle.rst:553 -msgid "Pickling Class Instances" -msgstr "" - -#: ../../library/pickle.rst:557 -msgid "" -"In this section, we describe the general mechanisms available to you to " -"define, customize, and control how class instances are pickled and unpickled." -msgstr "" - -#: ../../library/pickle.rst:560 -msgid "" -"In most cases, no additional code is needed to make instances picklable. By " -"default, pickle will retrieve the class and the attributes of an instance " -"via introspection. When a class instance is unpickled, its :meth:`~object." -"__init__` method is usually *not* invoked. The default behaviour first " -"creates an uninitialized instance and then restores the saved attributes. " -"The following code shows an implementation of this behaviour::" -msgstr "" - -#: ../../library/pickle.rst:575 -msgid "" -"Classes can alter the default behaviour by providing one or several special " -"methods:" -msgstr "" - -#: ../../library/pickle.rst:580 -msgid "" -"In protocols 2 and newer, classes that implements the :meth:" -"`__getnewargs_ex__` method can dictate the values passed to the :meth:" -"`__new__` method upon unpickling. The method must return a pair ``(args, " -"kwargs)`` where *args* is a tuple of positional arguments and *kwargs* a " -"dictionary of named arguments for constructing the object. Those will be " -"passed to the :meth:`__new__` method upon unpickling." -msgstr "" - -#: ../../library/pickle.rst:588 -msgid "" -"You should implement this method if the :meth:`__new__` method of your class " -"requires keyword-only arguments. Otherwise, it is recommended for " -"compatibility to implement :meth:`__getnewargs__`." -msgstr "" - -#: ../../library/pickle.rst:592 -msgid ":meth:`__getnewargs_ex__` is now used in protocols 2 and 3." -msgstr "" - -#: ../../library/pickle.rst:598 -msgid "" -"This method serves a similar purpose as :meth:`__getnewargs_ex__`, but " -"supports only positional arguments. It must return a tuple of arguments " -"``args`` which will be passed to the :meth:`__new__` method upon unpickling." -msgstr "" - -#: ../../library/pickle.rst:602 -msgid "" -":meth:`__getnewargs__` will not be called if :meth:`__getnewargs_ex__` is " -"defined." -msgstr "" - -#: ../../library/pickle.rst:605 -msgid "" -"Before Python 3.6, :meth:`__getnewargs__` was called instead of :meth:" -"`__getnewargs_ex__` in protocols 2 and 3." -msgstr "" - -#: ../../library/pickle.rst:612 -msgid "" -"Classes can further influence how their instances are pickled by overriding " -"the method :meth:`__getstate__`. It is called and the returned object is " -"pickled as the contents for the instance, instead of a default state. There " -"are several cases:" -msgstr "" - -#: ../../library/pickle.rst:617 -msgid "" -"For a class that has no instance :attr:`~object.__dict__` and no :attr:" -"`~object.__slots__`, the default state is ``None``." -msgstr "" - -#: ../../library/pickle.rst:620 -msgid "" -"For a class that has an instance :attr:`~object.__dict__` and no :attr:" -"`~object.__slots__`, the default state is ``self.__dict__``." -msgstr "" - -#: ../../library/pickle.rst:623 -msgid "" -"For a class that has an instance :attr:`~object.__dict__` and :attr:`~object." -"__slots__`, the default state is a tuple consisting of two dictionaries: " -"``self.__dict__``, and a dictionary mapping slot names to slot values. Only " -"slots that have a value are included in the latter." -msgstr "" - -#: ../../library/pickle.rst:629 -msgid "" -"For a class that has :attr:`~object.__slots__` and no instance :attr:" -"`~object.__dict__`, the default state is a tuple whose first item is " -"``None`` and whose second item is a dictionary mapping slot names to slot " -"values described in the previous bullet." -msgstr "" - -#: ../../library/pickle.rst:634 -msgid "" -"Added the default implementation of the ``__getstate__()`` method in the :" -"class:`object` class." -msgstr "" - -#: ../../library/pickle.rst:641 -msgid "" -"Upon unpickling, if the class defines :meth:`__setstate__`, it is called " -"with the unpickled state. In that case, there is no requirement for the " -"state object to be a dictionary. Otherwise, the pickled state must be a " -"dictionary and its items are assigned to the new instance's dictionary." -msgstr "" - -#: ../../library/pickle.rst:648 -msgid "" -"If :meth:`__reduce__` returns a state with value ``None`` at pickling, the :" -"meth:`__setstate__` method will not be called upon unpickling." -msgstr "" - -#: ../../library/pickle.rst:652 -msgid "" -"Refer to the section :ref:`pickle-state` for more information about how to " -"use the methods :meth:`~object.__getstate__` and :meth:`~object." -"__setstate__`." -msgstr "" - -#: ../../library/pickle.rst:657 -msgid "" -"At unpickling time, some methods like :meth:`~object.__getattr__`, :meth:" -"`~object.__getattribute__`, or :meth:`~object.__setattr__` may be called " -"upon the instance. In case those methods rely on some internal invariant " -"being true, the type should implement :meth:`~object.__new__` to establish " -"such an invariant, as :meth:`~object.__init__` is not called when unpickling " -"an instance." -msgstr "" - -#: ../../library/pickle.rst:666 -msgid "" -"As we shall see, pickle does not use directly the methods described above. " -"In fact, these methods are part of the copy protocol which implements the :" -"meth:`~object.__reduce__` special method. The copy protocol provides a " -"unified interface for retrieving the data necessary for pickling and copying " -"objects. [#]_" -msgstr "" - -#: ../../library/pickle.rst:672 -msgid "" -"Although powerful, implementing :meth:`~object.__reduce__` directly in your " -"classes is error prone. For this reason, class designers should use the " -"high-level interface (i.e., :meth:`~object.__getnewargs_ex__`, :meth:" -"`~object.__getstate__` and :meth:`~object.__setstate__`) whenever possible. " -"We will show, however, cases where using :meth:`!__reduce__` is the only " -"option or leads to more efficient pickling or both." -msgstr "" - -#: ../../library/pickle.rst:681 -msgid "" -"The interface is currently defined as follows. The :meth:`__reduce__` " -"method takes no argument and shall return either a string or preferably a " -"tuple (the returned object is often referred to as the \"reduce value\")." -msgstr "" - -#: ../../library/pickle.rst:685 -msgid "" -"If a string is returned, the string should be interpreted as the name of a " -"global variable. It should be the object's local name relative to its " -"module; the pickle module searches the module namespace to determine the " -"object's module. This behaviour is typically useful for singletons." -msgstr "" - -#: ../../library/pickle.rst:690 -msgid "" -"When a tuple is returned, it must be between two and six items long. " -"Optional items can either be omitted, or ``None`` can be provided as their " -"value. The semantics of each item are in order:" -msgstr "" - -#: ../../library/pickle.rst:696 -msgid "" -"A callable object that will be called to create the initial version of the " -"object." -msgstr "" - -#: ../../library/pickle.rst:699 -msgid "" -"A tuple of arguments for the callable object. An empty tuple must be given " -"if the callable does not accept any argument." -msgstr "" - -#: ../../library/pickle.rst:702 -msgid "" -"Optionally, the object's state, which will be passed to the object's :meth:" -"`__setstate__` method as previously described. If the object has no such " -"method then, the value must be a dictionary and it will be added to the " -"object's :attr:`~object.__dict__` attribute." -msgstr "" - -#: ../../library/pickle.rst:707 -msgid "" -"Optionally, an iterator (and not a sequence) yielding successive items. " -"These items will be appended to the object either using ``obj.append(item)`` " -"or, in batch, using ``obj.extend(list_of_items)``. This is primarily used " -"for list subclasses, but may be used by other classes as long as they have :" -"ref:`append and extend methods ` with the appropriate " -"signature. (Whether :meth:`!append` or :meth:`!extend` is used depends on " -"which pickle protocol version is used as well as the number of items to " -"append, so both must be supported.)" -msgstr "" - -#: ../../library/pickle.rst:717 -msgid "" -"Optionally, an iterator (not a sequence) yielding successive key-value " -"pairs. These items will be stored to the object using ``obj[key] = " -"value``. This is primarily used for dictionary subclasses, but may be used " -"by other classes as long as they implement :meth:`__setitem__`." -msgstr "" - -#: ../../library/pickle.rst:722 -msgid "" -"Optionally, a callable with a ``(obj, state)`` signature. This callable " -"allows the user to programmatically control the state-updating behavior of a " -"specific object, instead of using ``obj``'s static :meth:`__setstate__` " -"method. If not ``None``, this callable will have priority over ``obj``'s :" -"meth:`__setstate__`." -msgstr "" - -#: ../../library/pickle.rst:728 -msgid "The optional sixth tuple item, ``(obj, state)``, was added." -msgstr "" - -#: ../../library/pickle.rst:734 -msgid "" -"Alternatively, a :meth:`__reduce_ex__` method may be defined. The only " -"difference is this method should take a single integer argument, the " -"protocol version. When defined, pickle will prefer it over the :meth:" -"`__reduce__` method. In addition, :meth:`__reduce__` automatically becomes " -"a synonym for the extended version. The main use for this method is to " -"provide backwards-compatible reduce values for older Python releases." -msgstr "" - -#: ../../library/pickle.rst:746 -msgid "Persistence of External Objects" -msgstr "" - -#: ../../library/pickle.rst:752 -msgid "" -"For the benefit of object persistence, the :mod:`pickle` module supports the " -"notion of a reference to an object outside the pickled data stream. Such " -"objects are referenced by a persistent ID, which should be either a string " -"of alphanumeric characters (for protocol 0) [#]_ or just an arbitrary object " -"(for any newer protocol)." -msgstr "" - -#: ../../library/pickle.rst:758 -msgid "" -"The resolution of such persistent IDs is not defined by the :mod:`pickle` " -"module; it will delegate this resolution to the user-defined methods on the " -"pickler and unpickler, :meth:`~Pickler.persistent_id` and :meth:`~Unpickler." -"persistent_load` respectively." -msgstr "" - -#: ../../library/pickle.rst:763 -msgid "" -"To pickle objects that have an external persistent ID, the pickler must have " -"a custom :meth:`~Pickler.persistent_id` method that takes an object as an " -"argument and returns either ``None`` or the persistent ID for that object. " -"When ``None`` is returned, the pickler simply pickles the object as normal. " -"When a persistent ID string is returned, the pickler will pickle that " -"object, along with a marker so that the unpickler will recognize it as a " -"persistent ID." -msgstr "" - -#: ../../library/pickle.rst:770 -msgid "" -"To unpickle external objects, the unpickler must have a custom :meth:" -"`~Unpickler.persistent_load` method that takes a persistent ID object and " -"returns the referenced object." -msgstr "" - -#: ../../library/pickle.rst:774 -msgid "" -"Here is a comprehensive example presenting how persistent ID can be used to " -"pickle external objects by reference." -msgstr "" - -#: ../../library/pickle.rst:782 -msgid "Dispatch Tables" -msgstr "" - -#: ../../library/pickle.rst:784 -msgid "" -"If one wants to customize pickling of some classes without disturbing any " -"other code which depends on pickling, then one can create a pickler with a " -"private dispatch table." -msgstr "" - -#: ../../library/pickle.rst:788 -msgid "" -"The global dispatch table managed by the :mod:`copyreg` module is available " -"as :data:`!copyreg.dispatch_table`. Therefore, one may choose to use a " -"modified copy of :data:`!copyreg.dispatch_table` as a private dispatch table." -msgstr "" - -#: ../../library/pickle.rst:793 -msgid "For example ::" -msgstr "舉例來說： ::" - -#: ../../library/pickle.rst:800 -msgid "" -"creates an instance of :class:`pickle.Pickler` with a private dispatch table " -"which handles the ``SomeClass`` class specially. Alternatively, the code ::" -msgstr "" - -#: ../../library/pickle.rst:810 -msgid "" -"does the same but all instances of ``MyPickler`` will by default share the " -"private dispatch table. On the other hand, the code ::" -msgstr "" - -#: ../../library/pickle.rst:817 -msgid "" -"modifies the global dispatch table shared by all users of the :mod:`copyreg` " -"module." -msgstr "" - -#: ../../library/pickle.rst:822 -msgid "Handling Stateful Objects" -msgstr "" - -#: ../../library/pickle.rst:828 -msgid "" -"Here's an example that shows how to modify pickling behavior for a class. " -"The :class:`!TextReader` class below opens a text file, and returns the line " -"number and line contents each time its :meth:`!readline` method is called. " -"If a :class:`!TextReader` instance is pickled, all attributes *except* the " -"file object member are saved. When the instance is unpickled, the file is " -"reopened, and reading resumes from the last location. The :meth:`!" -"__setstate__` and :meth:`!__getstate__` methods are used to implement this " -"behavior. ::" -msgstr "" - -#: ../../library/pickle.rst:874 -msgid "A sample usage might be something like this::" -msgstr "" - -#: ../../library/pickle.rst:888 -msgid "Custom Reduction for Types, Functions, and Other Objects" -msgstr "" - -#: ../../library/pickle.rst:892 -msgid "" -"Sometimes, :attr:`~Pickler.dispatch_table` may not be flexible enough. In " -"particular we may want to customize pickling based on another criterion than " -"the object's type, or we may want to customize the pickling of functions and " -"classes." -msgstr "" - -#: ../../library/pickle.rst:897 -msgid "" -"For those cases, it is possible to subclass from the :class:`Pickler` class " -"and implement a :meth:`~Pickler.reducer_override` method. This method can " -"return an arbitrary reduction tuple (see :meth:`~object.__reduce__`). It can " -"alternatively return :data:`NotImplemented` to fallback to the traditional " -"behavior." -msgstr "" - -#: ../../library/pickle.rst:902 -msgid "" -"If both the :attr:`~Pickler.dispatch_table` and :meth:`~Pickler." -"reducer_override` are defined, then :meth:`~Pickler.reducer_override` method " -"takes priority." -msgstr "" - -#: ../../library/pickle.rst:907 -msgid "" -"For performance reasons, :meth:`~Pickler.reducer_override` may not be called " -"for the following objects: ``None``, ``True``, ``False``, and exact " -"instances of :class:`int`, :class:`float`, :class:`bytes`, :class:`str`, :" -"class:`dict`, :class:`set`, :class:`frozenset`, :class:`list` and :class:" -"`tuple`." -msgstr "" - -#: ../../library/pickle.rst:913 -msgid "" -"Here is a simple example where we allow pickling and reconstructing a given " -"class::" -msgstr "" - -#: ../../library/pickle.rst:948 -msgid "Out-of-band Buffers" -msgstr "" - -#: ../../library/pickle.rst:952 -msgid "" -"In some contexts, the :mod:`pickle` module is used to transfer massive " -"amounts of data. Therefore, it can be important to minimize the number of " -"memory copies, to preserve performance and resource consumption. However, " -"normal operation of the :mod:`pickle` module, as it transforms a graph-like " -"structure of objects into a sequential stream of bytes, intrinsically " -"involves copying data to and from the pickle stream." -msgstr "" - -#: ../../library/pickle.rst:959 -msgid "" -"This constraint can be eschewed if both the *provider* (the implementation " -"of the object types to be transferred) and the *consumer* (the " -"implementation of the communications system) support the out-of-band " -"transfer facilities provided by pickle protocol 5 and higher." -msgstr "" - -#: ../../library/pickle.rst:965 -msgid "Provider API" -msgstr "" - -#: ../../library/pickle.rst:967 -msgid "" -"The large data objects to be pickled must implement a :meth:`~object." -"__reduce_ex__` method specialized for protocol 5 and higher, which returns " -"a :class:`PickleBuffer` instance (instead of e.g. a :class:`bytes` object) " -"for any large data." -msgstr "" - -#: ../../library/pickle.rst:972 -msgid "" -"A :class:`PickleBuffer` object *signals* that the underlying buffer is " -"eligible for out-of-band data transfer. Those objects remain compatible " -"with normal usage of the :mod:`pickle` module. However, consumers can also " -"opt-in to tell :mod:`pickle` that they will handle those buffers by " -"themselves." -msgstr "" - -#: ../../library/pickle.rst:979 -msgid "Consumer API" -msgstr "" - -#: ../../library/pickle.rst:981 -msgid "" -"A communications system can enable custom handling of the :class:" -"`PickleBuffer` objects generated when serializing an object graph." -msgstr "" - -#: ../../library/pickle.rst:984 -msgid "" -"On the sending side, it needs to pass a *buffer_callback* argument to :class:" -"`Pickler` (or to the :func:`dump` or :func:`dumps` function), which will be " -"called with each :class:`PickleBuffer` generated while pickling the object " -"graph. Buffers accumulated by the *buffer_callback* will not see their data " -"copied into the pickle stream, only a cheap marker will be inserted." -msgstr "" - -#: ../../library/pickle.rst:991 -msgid "" -"On the receiving side, it needs to pass a *buffers* argument to :class:" -"`Unpickler` (or to the :func:`load` or :func:`loads` function), which is an " -"iterable of the buffers which were passed to *buffer_callback*. That " -"iterable should produce buffers in the same order as they were passed to " -"*buffer_callback*. Those buffers will provide the data expected by the " -"reconstructors of the objects whose pickling produced the original :class:" -"`PickleBuffer` objects." -msgstr "" - -#: ../../library/pickle.rst:999 -msgid "" -"Between the sending side and the receiving side, the communications system " -"is free to implement its own transfer mechanism for out-of-band buffers. " -"Potential optimizations include the use of shared memory or datatype-" -"dependent compression." -msgstr "" - -#: ../../library/pickle.rst:1005 -msgid "Example" -msgstr "範例" - -#: ../../library/pickle.rst:1007 -msgid "" -"Here is a trivial example where we implement a :class:`bytearray` subclass " -"able to participate in out-of-band buffer pickling::" -msgstr "" - -#: ../../library/pickle.rst:1031 -msgid "" -"The reconstructor (the ``_reconstruct`` class method) returns the buffer's " -"providing object if it has the right type. This is an easy way to simulate " -"zero-copy behaviour on this toy example." -msgstr "" - -#: ../../library/pickle.rst:1035 -msgid "" -"On the consumer side, we can pickle those objects the usual way, which when " -"unserialized will give us a copy of the original object::" -msgstr "" - -#: ../../library/pickle.rst:1044 -msgid "" -"But if we pass a *buffer_callback* and then give back the accumulated " -"buffers when unserializing, we are able to get back the original object::" -msgstr "" - -#: ../../library/pickle.rst:1054 -msgid "" -"This example is limited by the fact that :class:`bytearray` allocates its " -"own memory: you cannot create a :class:`bytearray` instance that is backed " -"by another object's memory. However, third-party datatypes such as NumPy " -"arrays do not have this limitation, and allow use of zero-copy pickling (or " -"making as few copies as possible) when transferring between distinct " -"processes or systems." -msgstr "" - -#: ../../library/pickle.rst:1061 -msgid ":pep:`574` -- Pickle protocol 5 with out-of-band data" -msgstr "" - -#: ../../library/pickle.rst:1067 -msgid "Restricting Globals" -msgstr "" - -#: ../../library/pickle.rst:1072 -msgid "" -"By default, unpickling will import any class or function that it finds in " -"the pickle data. For many applications, this behaviour is unacceptable as " -"it permits the unpickler to import and invoke arbitrary code. Just consider " -"what this hand-crafted pickle data stream does when loaded::" -msgstr "" - -#: ../../library/pickle.rst:1082 -msgid "" -"In this example, the unpickler imports the :func:`os.system` function and " -"then apply the string argument \"echo hello world\". Although this example " -"is inoffensive, it is not difficult to imagine one that could damage your " -"system." -msgstr "" - -#: ../../library/pickle.rst:1086 -msgid "" -"For this reason, you may want to control what gets unpickled by customizing :" -"meth:`Unpickler.find_class`. Unlike its name suggests, :meth:`Unpickler." -"find_class` is called whenever a global (i.e., a class or a function) is " -"requested. Thus it is possible to either completely forbid globals or " -"restrict them to a safe subset." -msgstr "" - -#: ../../library/pickle.rst:1092 -msgid "" -"Here is an example of an unpickler allowing only few safe classes from the :" -"mod:`builtins` module to be loaded::" -msgstr "" - -#: ../../library/pickle.rst:1121 -msgid "A sample usage of our unpickler working as intended::" -msgstr "" - -#: ../../library/pickle.rst:1140 -msgid "" -"As our examples shows, you have to be careful with what you allow to be " -"unpickled. Therefore if security is a concern, you may want to consider " -"alternatives such as the marshalling API in :mod:`xmlrpc.client` or third-" -"party solutions." -msgstr "" - -#: ../../library/pickle.rst:1147 -msgid "Performance" -msgstr "" - -#: ../../library/pickle.rst:1149 -msgid "" -"Recent versions of the pickle protocol (from protocol 2 and upwards) feature " -"efficient binary encodings for several common features and built-in types. " -"Also, the :mod:`pickle` module has a transparent optimizer written in C." -msgstr "" - -#: ../../library/pickle.rst:1157 -msgid "Examples" -msgstr "範例" - -#: ../../library/pickle.rst:1159 -msgid "" -"For the simplest code, use the :func:`dump` and :func:`load` functions. ::" -msgstr "" - -#: ../../library/pickle.rst:1175 -msgid "The following example reads the resulting pickled data. ::" -msgstr "" - -#: ../../library/pickle.rst:1191 -msgid "Module :mod:`copyreg`" -msgstr ":mod:`copyreg` 模組" - -#: ../../library/pickle.rst:1192 -msgid "Pickle interface constructor registration for extension types." -msgstr "" - -#: ../../library/pickle.rst:1194 -msgid "Module :mod:`pickletools`" -msgstr ":mod:`pickletools` 模組" - -#: ../../library/pickle.rst:1195 -msgid "Tools for working with and analyzing pickled data." -msgstr "" - -#: ../../library/pickle.rst:1197 -msgid "Module :mod:`shelve`" -msgstr ":mod:`shelve` 模組" - -#: ../../library/pickle.rst:1198 -msgid "Indexed databases of objects; uses :mod:`pickle`." -msgstr "" - -#: ../../library/pickle.rst:1200 -msgid "Module :mod:`copy`" -msgstr ":mod:`copy` 模組" - -#: ../../library/pickle.rst:1201 -msgid "Shallow and deep object copying." -msgstr "" - -#: ../../library/pickle.rst:1203 -msgid "Module :mod:`marshal`" -msgstr ":mod:`marshal` 模組" - -#: ../../library/pickle.rst:1204 -msgid "High-performance serialization of built-in types." -msgstr "" - -#: ../../library/pickle.rst:1208 -msgid "Footnotes" -msgstr "註解" - -#: ../../library/pickle.rst:1209 -msgid "Don't confuse this with the :mod:`marshal` module" -msgstr "" - -#: ../../library/pickle.rst:1211 -msgid "" -"This is why :keyword:`lambda` functions cannot be pickled: all :keyword:`!" -"lambda` functions share the same name: ````." -msgstr "" - -#: ../../library/pickle.rst:1214 -msgid "" -"The exception raised will likely be an :exc:`ImportError` or an :exc:" -"`AttributeError` but it could be something else." -msgstr "" - -#: ../../library/pickle.rst:1217 -msgid "" -"The :mod:`copy` module uses this protocol for shallow and deep copying " -"operations." -msgstr "" - -#: ../../library/pickle.rst:1220 -msgid "" -"The limitation on alphanumeric characters is due to the fact that persistent " -"IDs in protocol 0 are delimited by the newline character. Therefore if any " -"kind of newline characters occurs in persistent IDs, the resulting pickled " -"data will become unreadable." -msgstr "" - -#: ../../library/pickle.rst:12 -msgid "persistence" -msgstr "persistence（持續性）" - -#: ../../library/pickle.rst:12 -msgid "persistent" -msgstr "persistent（持續）" - -#: ../../library/pickle.rst:12 -msgid "objects" -msgstr "objects（物件）" - -#: ../../library/pickle.rst:12 -msgid "serializing" -msgstr "serializing（序列化）" - -#: ../../library/pickle.rst:12 -msgid "marshalling" -msgstr "marshalling" - -#: ../../library/pickle.rst:12 -msgid "flattening" -msgstr "flattening（攤平）" - -#: ../../library/pickle.rst:12 -msgid "pickling" -msgstr "pickling" - -#: ../../library/pickle.rst:123 -msgid "External Data Representation" -msgstr "External Data Representation（外部資料表示法）" - -#: ../../library/pickle.rst:664 -msgid "copy" -msgstr "copy（複製）" - -#: ../../library/pickle.rst:664 -msgid "protocol" -msgstr "protocol（協定）" - -#: ../../library/pickle.rst:748 -msgid "persistent_id (pickle protocol)" -msgstr "persistent_id（pickle 協定）" - -#: ../../library/pickle.rst:748 -msgid "persistent_load (pickle protocol)" -msgstr "persistent_load（pickle 協定）" - -#: ../../library/pickle.rst:824 -msgid "__getstate__() (copy protocol)" -msgstr "__getstate__()（copy 協定）" - -#: ../../library/pickle.rst:824 -msgid "__setstate__() (copy protocol)" -msgstr "__setstate__()（copy 協定）" - -#: ../../library/pickle.rst:1069 -msgid "find_class() (pickle protocol)" -msgstr "find_class()（pickle 協定）" +# Copyright (C) 2001-2024, Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Skylull, 2024 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.12\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-05-09 00:03+0000\n" +"PO-Revision-Date: 2018-05-23 16:07+0000\n" +"Last-Translator: Adrian Liaw \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" +"Plural-Forms: nplurals=1; plural=0;\n" + +#: ../../library/pickle.rst:2 +msgid ":mod:`!pickle` --- Python object serialization" +msgstr ":mod:`!pickle` --- Python 物件序列化" + +#: ../../library/pickle.rst:10 +msgid "**Source code:** :source:`Lib/pickle.py`" +msgstr "**原始碼：**\\ :source:`Lib/pickle.py`" + +# Skylull: 我對 `pickle` 的命名原因進行了簡單的搜尋，只找到一則討論 +# https://stackoverflow.com/questions/27324986/pickles-why-are-they-called- +# that +# 其中表示這名字很可能只是為了隨便找一個p開頭的單字、或原始開發人員的內部玩笑造成的約定俗成。也有人表示醃製黃瓜（pickle- +# ing）的目標就是保存和存放，所以取了這個名字。 +# 無論如何似乎沒有一個定論。 +# 因為不確定是否與醃漬的這個梗有關，我暫時選擇使用 `封裝` 與 `拆封` 作為譯文，大致保存那個把東西處裡後裝起來的感覺但又不至於太奇怪。 +# 唯一需要擔心的是是否有與 `encapsulation` （封裝，網路協定名詞）或 `package`（封包，網路協定名詞）搞混的可能。 +#: ../../library/pickle.rst:22 +msgid "" +"The :mod:`pickle` module implements binary protocols for serializing and de-" +"serializing a Python object structure. *\"Pickling\"* is the process " +"whereby a Python object hierarchy is converted into a byte stream, and " +"*\"unpickling\"* is the inverse operation, whereby a byte stream (from a " +":term:`binary file` or :term:`bytes-like object`) is converted back into an " +"object hierarchy. Pickling (and unpickling) is alternatively known as " +"\"serialization\", \"marshalling,\" [#]_ or \"flattening\"; however, to " +"avoid confusion, the terms used here are \"pickling\" and \"unpickling\"." +msgstr "" +":mod:`pickle` 模組實作的是一個在二進位層級上對 Python 物件進行序列化（serialize）或去序列化（de-" +"serialize）。*\"Pickling\"* 用於專門指摘將一個 Python 物件轉換為一個二進位串流的過程，*\"unpickling\"* " +"則相反，指的是將一個（來自 :term:`binary file` 或 :term:`bytes-like object` 的）二進位串流轉換回 " +"Python 物件的過程。Pickling（和 unpickling）的過程也可能被稱作 \"serialization\", " +"\"marshalling,\" [#]_ 或 " +"\"flattening\"。不過，為了避免混淆，本文件將統一稱作封裝（pickling）、拆封（unpickling）。" + +#: ../../library/pickle.rst:33 +msgid "The ``pickle`` module **is not secure**. Only unpickle data you trust." +msgstr "``pickle`` 模組**並不安全**，切記只拆封你信任的資料。" + +#: ../../library/pickle.rst:35 +msgid "" +"It is possible to construct malicious pickle data which will **execute " +"arbitrary code during unpickling**. Never unpickle data that could have come" +" from an untrusted source, or that could have been tampered with." +msgstr "" +"pickle 封包是有可能被建立來在拆封的時候**執行任意惡意程式碼**的。絕對不要拆封任何你無法信任其來源、或可能被修改過的 pickle 封包。" + +#: ../../library/pickle.rst:39 +msgid "" +"Consider signing data with :mod:`hmac` if you need to ensure that it has not" +" been tampered with." +msgstr "建議你可以使用 :mod:`hmac` 模組來簽署這個封包，以確保其未被修改過。" + +#: ../../library/pickle.rst:42 +msgid "" +"Safer serialization formats such as :mod:`json` may be more appropriate if " +"you are processing untrusted data. See :ref:`comparison-with-json`." +msgstr "" +"如果你在處理不受信任的資料，其他比較安全的序列化格式（例如 :mod:`json`）可能會更適合。請參照 See :ref:`comparison-" +"with-json` 的說明。" + +#: ../../library/pickle.rst:47 +msgid "Relationship to other Python modules" +msgstr "和其他 Python 模組的關係" + +#: ../../library/pickle.rst:50 +msgid "Comparison with ``marshal``" +msgstr "和 ``marshal`` 的比較" + +#: ../../library/pickle.rst:52 +msgid "" +"Python has a more primitive serialization module called :mod:`marshal`, but " +"in general :mod:`pickle` should always be the preferred way to serialize " +"Python objects. :mod:`marshal` exists primarily to support Python's " +":file:`.pyc` files." +msgstr "" +"Python 有另一個比較原始的序列化模組叫 :mod:`marshal`，不過其設計目的是為了支援 Python 的預編譯功能 " +":file:`.pyc` 運作。總地來說，沒事不要用 :mod:`marshal`。" + +#: ../../library/pickle.rst:57 +msgid "" +"The :mod:`pickle` module differs from :mod:`marshal` in several significant " +"ways:" +msgstr ":mod:`pickle` 和 :mod:`marshal` 有幾個明顯不同的地方：" + +#: ../../library/pickle.rst:59 +msgid "" +"The :mod:`pickle` module keeps track of the objects it has already " +"serialized, so that later references to the same object won't be serialized " +"again. :mod:`marshal` doesn't do this." +msgstr "" +":mod:`pickle` 會記住哪些物件已經被序列化過了，稍後再次參照到這個物件的時候才不會進行重複的序列化。:mod:`marshal` " +"沒有這個功能。" + +#: ../../library/pickle.rst:63 +msgid "" +"This has implications both for recursive objects and object sharing. " +"Recursive objects are objects that contain references to themselves. These " +"are not handled by marshal, and in fact, attempting to marshal recursive " +"objects will crash your Python interpreter. Object sharing happens when " +"there are multiple references to the same object in different places in the " +"object hierarchy being serialized. :mod:`pickle` stores such objects only " +"once, and ensures that all other references point to the master copy. " +"Shared objects remain shared, which can be very important for mutable " +"objects." +msgstr "" +"這對遞迴物件和物件共用都有影響。遞迴物件是指包含自我參照的物件。這些情況在 marshal 模組中不會被處理，若嘗試使用 marshal " +"處理遞迴物件會導致 Python 直譯器崩潰。物件共用發生在序列化的物件階層中，不同位置對同一物件有多個參照時。:mod:`pickle` " +"只會儲存這個被參照的物件一次，並確保所有其他參照指向這個主要的版本。共用的物件會保持共用，這對於可變（mutable）物件來說非常重要。" + +#: ../../library/pickle.rst:72 +msgid "" +":mod:`marshal` cannot be used to serialize user-defined classes and their " +"instances. :mod:`pickle` can save and restore class instances " +"transparently, however the class definition must be importable and live in " +"the same module as when the object was stored." +msgstr "" +":mod:`marshal` 無法序列化使用者自訂的類別和的實例。:mod:`pickle` " +"則可以讓使用者儲存並還原自訂的類別實例，前提是儲存時該類別的定義存在於與要被儲存的物件所在的模組中、且可以被引入（import）。" + +#: ../../library/pickle.rst:77 +msgid "" +"The :mod:`marshal` serialization format is not guaranteed to be portable " +"across Python versions. Because its primary job in life is to support " +":file:`.pyc` files, the Python implementers reserve the right to change the " +"serialization format in non-backwards compatible ways should the need arise." +" The :mod:`pickle` serialization format is guaranteed to be backwards " +"compatible across Python releases provided a compatible pickle protocol is " +"chosen and pickling and unpickling code deals with Python 2 to Python 3 type" +" differences if your data is crossing that unique breaking change language " +"boundary." +msgstr "" +":mod:`marshal` 序列化格式無法保證能在不同版本的 Python 之間移植。因為其主要的作用是支援 :file:`.pyc` " +"檔案的運作，Python 的實作人員會在需要時實作無法前向相容的序列化方式。但只要選擇了相容的 pickle 協定，且處理了 Python 2 和 " +"Python 3 之間的資料類型差異，:mod:`pickle` 序列化協定能保證在不同 Python 版本間的相容性。" + +#: ../../library/pickle.rst:90 +msgid "Comparison with ``json``" +msgstr "和 ``json`` 的比較" + +#: ../../library/pickle.rst:92 +msgid "" +"There are fundamental differences between the pickle protocols and `JSON " +"(JavaScript Object Notation) `_:" +msgstr "" +"pickle 協定和 `JSON (JavaScript Object Notation) `_ " +"有一些根本上的不同：" + +#: ../../library/pickle.rst:95 +msgid "" +"JSON is a text serialization format (it outputs unicode text, although most " +"of the time it is then encoded to ``utf-8``), while pickle is a binary " +"serialization format;" +msgstr "" +"JSON 以文字形式作為序列化的輸出（輸出 unicode 文字，但大多數又會被編碼為 ``UTF-8``），而 pickle " +"則是以二進位形式作為序列化的輸出；" + +#: ../../library/pickle.rst:99 +msgid "JSON is human-readable, while pickle is not;" +msgstr "JSON 是人類可讀的，而 pickle 則無法；" + +#: ../../library/pickle.rst:101 +msgid "" +"JSON is interoperable and widely used outside of the Python ecosystem, while" +" pickle is Python-specific;" +msgstr "" +"JSON 具有高互通性（interoperability）且在 Python 以外的環境也被大量利用，但 pickle 只能在 Python 內使用。" + +# Skylull: introspection, introspection facilities +# https://zh.wikipedia.org/wiki/%E5%86%85%E7%9C%81_(%E8%AE%A1%E7%AE%97%E6%9C%BA%E7%A7%91%E5%AD%A6) +# https://book.pythontips.com/en/latest/object_introspection.html +# https://www.geeksforgeeks.org/code-introspection-in-python/ +#: ../../library/pickle.rst:104 +msgid "" +"JSON, by default, can only represent a subset of the Python built-in types, " +"and no custom classes; pickle can represent an extremely large number of " +"Python types (many of them automatically, by clever usage of Python's " +"introspection facilities; complex cases can be tackled by implementing " +":ref:`specific object APIs `);" +msgstr "" +"預設狀態下的 JSON 只能紀錄一小部份的 Python 內建型別，且無法紀錄自訂類別；但透過 Python 的自省功能，pickle " +"可以紀錄絕大多數的 Python 型別（其他比較複雜的狀況也可以透過實作 :ref:`specific object APIs ` 來解決）；" + +#: ../../library/pickle.rst:110 +msgid "" +"Unlike pickle, deserializing untrusted JSON does not in itself create an " +"arbitrary code execution vulnerability." +msgstr "去序列化不安全的 JSON 不會產生任意程式執行的風險，但去序列化不安全的 pickle 會。" + +#: ../../library/pickle.rst:114 +msgid "" +"The :mod:`json` module: a standard library module allowing JSON " +"serialization and deserialization." +msgstr ":mod:`json` module: 是標準函式庫的一部分，可讓使用者進行 JSON 的序列化與去序列化。" + +#: ../../library/pickle.rst:121 +msgid "Data stream format" +msgstr "資料串流格式" + +#: ../../library/pickle.rst:126 +msgid "" +"The data format used by :mod:`pickle` is Python-specific. This has the " +"advantage that there are no restrictions imposed by external standards such " +"as JSON or XDR (which can't represent pointer sharing); however it means " +"that non-Python programs may not be able to reconstruct pickled Python " +"objects." +msgstr "" +":mod:`pickle` 使用的資料格式是針對 Python 而設計的。好處是他不會受到外部標準（像是 JSON 或 XDR，而 XDR " +"無法紀錄指標共用）的限制；不過這也代表其他不是 Python 的程式可能無法重建 pickle 封裝的 Python 物件。" + +#: ../../library/pickle.rst:131 +msgid "" +"By default, the :mod:`pickle` data format uses a relatively compact binary " +"representation. If you need optimal size characteristics, you can " +"efficiently :doc:`compress ` pickled data." +msgstr "" +"以預設設定來說，:mod:`pickle` 使用相對緊湊的二進位形式來儲存資料。如果你需要盡可能地縮小檔案大小，你可以\\\\ :doc:`壓縮 " +"`\\\\ 封裝的資料。" + +#: ../../library/pickle.rst:135 +msgid "" +"The module :mod:`pickletools` contains tools for analyzing data streams " +"generated by :mod:`pickle`. :mod:`pickletools` source code has extensive " +"comments about opcodes used by pickle protocols." +msgstr "" +":mod:`pickletools` 含有工具可分析 :mod:`pickle` 所產生的資料流。:mod:`pickletools` " +"的源始碼詳細地記載了所有 pickle 協定的操作碼（opcode）。" + +#: ../../library/pickle.rst:139 +msgid "" +"There are currently 6 different protocols which can be used for pickling. " +"The higher the protocol used, the more recent the version of Python needed " +"to read the pickle produced." +msgstr "" +"截至目前為止，共有六種不同版本的協定可用於封裝 pickle。數字越大版本代表你需要使用越新的 Python 版本來拆封相應的 pickle 封裝。" + +#: ../../library/pickle.rst:143 +msgid "" +"Protocol version 0 is the original \"human-readable\" protocol and is " +"backwards compatible with earlier versions of Python." +msgstr "版本 0 的協定是最初「人類可讀」的版本，且可以向前支援早期版本的 Python。" + +#: ../../library/pickle.rst:146 +msgid "" +"Protocol version 1 is an old binary format which is also compatible with " +"earlier versions of Python." +msgstr "版本 1 的協定使用舊的二進位格式，一樣能向前支援早期版本的 Python。" + +#: ../../library/pickle.rst:149 +msgid "" +"Protocol version 2 was introduced in Python 2.3. It provides much more " +"efficient pickling of :term:`new-style classes `. Refer to" +" :pep:`307` for information about improvements brought by protocol 2." +msgstr "" +"版本 2 的協定在 Python 2.3 中初次被引入。其可提供更高效率的 :term:`new-style classes ` 封裝過程。請參閱 :pep:`307` 以了解版本 2 帶來的改進。" + +#: ../../library/pickle.rst:153 +msgid "" +"Protocol version 3 was added in Python 3.0. It has explicit support for " +":class:`bytes` objects and cannot be unpickled by Python 2.x. This was the " +"default protocol in Python 3.0--3.7." +msgstr "" +"版本 3 的協定在 Python 3.0 被新增。現在能支援封裝 :class:`bytes` 的物件且無法被 2.x 版本的 Python 拆封。在 " +"3.0～3.7 的 Python 預設使用 3 版協定。" + +#: ../../library/pickle.rst:157 +msgid "" +"Protocol version 4 was added in Python 3.4. It adds support for very large " +"objects, pickling more kinds of objects, and some data format optimizations." +" It is the default protocol starting with Python 3.8. Refer to :pep:`3154` " +"for information about improvements brought by protocol 4." +msgstr "" +"版本 4 的協定在 Python 3.4 被新增。現在能支援超大物件的封裝、更多種型別的物件以及針對部份資料格式的儲存進行最佳化。從 Python " +"3.8 起，預設使用第 4 版協定。請參閱 :pep:`3154` 以了解第 4 版協定改進的細節。" + +#: ../../library/pickle.rst:163 +msgid "" +"Protocol version 5 was added in Python 3.8. It adds support for out-of-band" +" data and speedup for in-band data. Refer to :pep:`574` for information " +"about improvements brought by protocol 5." +msgstr "" +"版本 5 的協定在 Python 3.8 被新增。現在能支援帶外資料（Out-of-band data）並加速帶內資料的處理速度。請參閱 " +":pep:`574` 以了解第 5 版協定改進的細節。" + +#: ../../library/pickle.rst:168 +msgid "" +"Serialization is a more primitive notion than persistence; although " +":mod:`pickle` reads and writes file objects, it does not handle the issue of" +" naming persistent objects, nor the (even more complicated) issue of " +"concurrent access to persistent objects. The :mod:`pickle` module can " +"transform a complex object into a byte stream and it can transform the byte " +"stream into an object with the same internal structure. Perhaps the most " +"obvious thing to do with these byte streams is to write them onto a file, " +"but it is also conceivable to send them across a network or store them in a " +"database. The :mod:`shelve` module provides a simple interface to pickle " +"and unpickle objects on DBM-style database files." +msgstr "" +"資料序列化是一個比資料持久化更早出現的概念；雖然 :mod:`pickle` " +"可以讀寫檔案物件，但它並不處理命名持久物件的問題，也不處理對持久物件的並行存取、一個更棘手的問題。:mod:`pickle` " +"模組可以將複雜物件轉換成位元組串流，也可以將位元組串流轉換回具有相同原始內部結構的物件。對這些位元組串流最常見的處理方式是將它們寫入檔案中，但也可以將它們透過網路傳送或儲存在一個資料庫中。:mod:`shelve`" +" 模組提供了一個簡單的介面來讓使用者在 DBM 風格的資料庫檔案中對物件進行封裝和拆封的操作。" + +#: ../../library/pickle.rst:181 +msgid "Module Interface" +msgstr "模組介面" + +#: ../../library/pickle.rst:183 +msgid "" +"To serialize an object hierarchy, you simply call the :func:`dumps` " +"function. Similarly, to de-serialize a data stream, you call the " +":func:`loads` function. However, if you want more control over serialization" +" and de-serialization, you can create a :class:`Pickler` or an " +":class:`Unpickler` object, respectively." +msgstr "" +"想要序列化一個物件，你只需要呼叫 :func:`dumps` 函數。而當你想要去序列化一個資料流時，你只需要呼叫 :func:`loads` " +"即可。不過，若你希望能各自對序列化和去序列化的過程中有更多的掌控度，你可以自訂一個 :class:`Pickler` 或 " +":class:`Unpickler` 物件。" + +#: ../../library/pickle.rst:188 +msgid "The :mod:`pickle` module provides the following constants:" +msgstr ":mod:`pickle` 模組提供以下常數：" + +#: ../../library/pickle.rst:193 +msgid "" +"An integer, the highest :ref:`protocol version ` " +"available. This value can be passed as a *protocol* value to functions " +":func:`dump` and :func:`dumps` as well as the :class:`Pickler` constructor." +msgstr "" +"一個整數，表示可使用的最高\\\\ :ref:`協定版本 `。這個值可作為 *protocol* 的數值傳給 " +":func:`dump` 和 :func:`dumps` 函數以及 :class:`Pickler` 建構式。" + +#: ../../library/pickle.rst:200 +msgid "" +"An integer, the default :ref:`protocol version ` used for " +"pickling. May be less than :data:`HIGHEST_PROTOCOL`. Currently the default" +" protocol is 4, first introduced in Python 3.4 and incompatible with " +"previous versions." +msgstr "" +"一個整數，指示用於序列化的預設\\\\ :ref:`協定版本 `。有可能小於 " +":data:`HIGHEST_PROTOCOL`。目前的預設協定版本為 4，是在 Python 3.4 中首次引入的，且與先前版本不相容。" + +#: ../../library/pickle.rst:207 +msgid "The default protocol is 3." +msgstr "預設協定版本為 3。" + +#: ../../library/pickle.rst:211 +msgid "The default protocol is 4." +msgstr "預設協定版本為 4。" + +#: ../../library/pickle.rst:213 +msgid "" +"The :mod:`pickle` module provides the following functions to make the " +"pickling process more convenient:" +msgstr ":mod:`pickle` 模組提供下列函數來簡化封裝的過程：" + +#: ../../library/pickle.rst:218 +msgid "" +"Write the pickled representation of the object *obj* to the open :term:`file" +" object` *file*. This is equivalent to ``Pickler(file, " +"protocol).dump(obj)``." +msgstr "" + +#: ../../library/pickle.rst:222 +msgid "" +"Arguments *file*, *protocol*, *fix_imports* and *buffer_callback* have the " +"same meaning as in the :class:`Pickler` constructor." +msgstr "" + +#: ../../library/pickle.rst:225 ../../library/pickle.rst:236 +#: ../../library/pickle.rst:328 +msgid "The *buffer_callback* argument was added." +msgstr "新增 *buffer_callback* 引數。" + +#: ../../library/pickle.rst:230 +msgid "" +"Return the pickled representation of the object *obj* as a :class:`bytes` " +"object, instead of writing it to a file." +msgstr "" + +#: ../../library/pickle.rst:233 +msgid "" +"Arguments *protocol*, *fix_imports* and *buffer_callback* have the same " +"meaning as in the :class:`Pickler` constructor." +msgstr "" + +#: ../../library/pickle.rst:241 +msgid "" +"Read the pickled representation of an object from the open :term:`file " +"object` *file* and return the reconstituted object hierarchy specified " +"therein. This is equivalent to ``Unpickler(file).load()``." +msgstr "" + +#: ../../library/pickle.rst:245 ../../library/pickle.rst:260 +msgid "" +"The protocol version of the pickle is detected automatically, so no protocol" +" argument is needed. Bytes past the pickled representation of the object " +"are ignored." +msgstr "" + +#: ../../library/pickle.rst:249 +msgid "" +"Arguments *file*, *fix_imports*, *encoding*, *errors*, *strict* and " +"*buffers* have the same meaning as in the :class:`Unpickler` constructor." +msgstr "" + +#: ../../library/pickle.rst:252 ../../library/pickle.rst:267 +#: ../../library/pickle.rst:429 +msgid "The *buffers* argument was added." +msgstr "新增 *buffer* 引數。" + +#: ../../library/pickle.rst:257 +msgid "" +"Return the reconstituted object hierarchy of the pickled representation " +"*data* of an object. *data* must be a :term:`bytes-like object`." +msgstr "" + +#: ../../library/pickle.rst:264 +msgid "" +"Arguments *fix_imports*, *encoding*, *errors*, *strict* and *buffers* have " +"the same meaning as in the :class:`Unpickler` constructor." +msgstr "" + +#: ../../library/pickle.rst:271 +msgid "The :mod:`pickle` module defines three exceptions:" +msgstr "" + +#: ../../library/pickle.rst:275 +msgid "" +"Common base class for the other pickling exceptions. It inherits from " +":exc:`Exception`." +msgstr "" + +#: ../../library/pickle.rst:280 +msgid "" +"Error raised when an unpicklable object is encountered by :class:`Pickler`. " +"It inherits from :exc:`PickleError`." +msgstr "" + +#: ../../library/pickle.rst:283 +msgid "" +"Refer to :ref:`pickle-picklable` to learn what kinds of objects can be " +"pickled." +msgstr "" + +#: ../../library/pickle.rst:288 +msgid "" +"Error raised when there is a problem unpickling an object, such as a data " +"corruption or a security violation. It inherits from :exc:`PickleError`." +msgstr "" + +#: ../../library/pickle.rst:291 +msgid "" +"Note that other exceptions may also be raised during unpickling, including " +"(but not necessarily limited to) AttributeError, EOFError, ImportError, and " +"IndexError." +msgstr "" + +#: ../../library/pickle.rst:296 +msgid "" +"The :mod:`pickle` module exports three classes, :class:`Pickler`, " +":class:`Unpickler` and :class:`PickleBuffer`:" +msgstr "" + +#: ../../library/pickle.rst:301 +msgid "This takes a binary file for writing a pickle data stream." +msgstr "" + +#: ../../library/pickle.rst:303 +msgid "" +"The optional *protocol* argument, an integer, tells the pickler to use the " +"given protocol; supported protocols are 0 to :data:`HIGHEST_PROTOCOL`. If " +"not specified, the default is :data:`DEFAULT_PROTOCOL`. If a negative " +"number is specified, :data:`HIGHEST_PROTOCOL` is selected." +msgstr "" + +#: ../../library/pickle.rst:308 +msgid "" +"The *file* argument must have a write() method that accepts a single bytes " +"argument. It can thus be an on-disk file opened for binary writing, an " +":class:`io.BytesIO` instance, or any other custom object that meets this " +"interface." +msgstr "" + +#: ../../library/pickle.rst:313 +msgid "" +"If *fix_imports* is true and *protocol* is less than 3, pickle will try to " +"map the new Python 3 names to the old module names used in Python 2, so that" +" the pickle data stream is readable with Python 2." +msgstr "" + +#: ../../library/pickle.rst:317 +msgid "" +"If *buffer_callback* is ``None`` (the default), buffer views are serialized " +"into *file* as part of the pickle stream." +msgstr "" + +#: ../../library/pickle.rst:320 +msgid "" +"If *buffer_callback* is not ``None``, then it can be called any number of " +"times with a buffer view. If the callback returns a false value (such as " +"``None``), the given buffer is :ref:`out-of-band `; otherwise " +"the buffer is serialized in-band, i.e. inside the pickle stream." +msgstr "" + +#: ../../library/pickle.rst:325 +msgid "" +"It is an error if *buffer_callback* is not ``None`` and *protocol* is " +"``None`` or smaller than 5." +msgstr "" + +#: ../../library/pickle.rst:333 +msgid "" +"Write the pickled representation of *obj* to the open file object given in " +"the constructor." +msgstr "" + +#: ../../library/pickle.rst:338 +msgid "Do nothing by default. This exists so a subclass can override it." +msgstr "" + +#: ../../library/pickle.rst:340 +msgid "" +"If :meth:`persistent_id` returns ``None``, *obj* is pickled as usual. Any " +"other value causes :class:`Pickler` to emit the returned value as a " +"persistent ID for *obj*. The meaning of this persistent ID should be " +"defined by :meth:`Unpickler.persistent_load`. Note that the value returned " +"by :meth:`persistent_id` cannot itself have a persistent ID." +msgstr "" + +#: ../../library/pickle.rst:346 ../../library/pickle.rst:447 +msgid "See :ref:`pickle-persistent` for details and examples of uses." +msgstr "關於細節與用法範例請見 :ref:`pickle-persistent`。" + +#: ../../library/pickle.rst:350 +msgid "" +"A pickler object's dispatch table is a registry of *reduction functions* of " +"the kind which can be declared using :func:`copyreg.pickle`. It is a " +"mapping whose keys are classes and whose values are reduction functions. A " +"reduction function takes a single argument of the associated class and " +"should conform to the same interface as a :meth:`~object.__reduce__` method." +msgstr "" + +#: ../../library/pickle.rst:358 +msgid "" +"By default, a pickler object will not have a :attr:`dispatch_table` " +"attribute, and it will instead use the global dispatch table managed by the " +":mod:`copyreg` module. However, to customize the pickling for a specific " +"pickler object one can set the :attr:`dispatch_table` attribute to a dict-" +"like object. Alternatively, if a subclass of :class:`Pickler` has a " +":attr:`dispatch_table` attribute then this will be used as the default " +"dispatch table for instances of that class." +msgstr "" + +#: ../../library/pickle.rst:367 +msgid "See :ref:`pickle-dispatch` for usage examples." +msgstr "關於用法範例請見 :ref:`pickle-dispatch`。" + +#: ../../library/pickle.rst:373 +msgid "" +"Special reducer that can be defined in :class:`Pickler` subclasses. This " +"method has priority over any reducer in the :attr:`dispatch_table`. It " +"should conform to the same interface as a :meth:`~object.__reduce__` method," +" and can optionally return :data:`NotImplemented` to fallback on " +":attr:`dispatch_table`-registered reducers to pickle ``obj``." +msgstr "" + +#: ../../library/pickle.rst:379 +msgid "For a detailed example, see :ref:`reducer_override`." +msgstr "" + +#: ../../library/pickle.rst:385 +msgid "" +"Deprecated. Enable fast mode if set to a true value. The fast mode disables" +" the usage of memo, therefore speeding the pickling process by not " +"generating superfluous PUT opcodes. It should not be used with self-" +"referential objects, doing otherwise will cause :class:`Pickler` to recurse " +"infinitely." +msgstr "" + +#: ../../library/pickle.rst:391 +msgid "Use :func:`pickletools.optimize` if you need more compact pickles." +msgstr "" + +#: ../../library/pickle.rst:396 +msgid "This takes a binary file for reading a pickle data stream." +msgstr "" + +#: ../../library/pickle.rst:398 +msgid "" +"The protocol version of the pickle is detected automatically, so no protocol" +" argument is needed." +msgstr "" + +#: ../../library/pickle.rst:401 +msgid "" +"The argument *file* must have three methods, a read() method that takes an " +"integer argument, a readinto() method that takes a buffer argument and a " +"readline() method that requires no arguments, as in the " +":class:`io.BufferedIOBase` interface. Thus *file* can be an on-disk file " +"opened for binary reading, an :class:`io.BytesIO` object, or any other " +"custom object that meets this interface." +msgstr "" + +#: ../../library/pickle.rst:408 +msgid "" +"The optional arguments *fix_imports*, *encoding* and *errors* are used to " +"control compatibility support for pickle stream generated by Python 2. If " +"*fix_imports* is true, pickle will try to map the old Python 2 names to the " +"new names used in Python 3. The *encoding* and *errors* tell pickle how to " +"decode 8-bit string instances pickled by Python 2; these default to 'ASCII' " +"and 'strict', respectively. The *encoding* can be 'bytes' to read these " +"8-bit string instances as bytes objects. Using ``encoding='latin1'`` is " +"required for unpickling NumPy arrays and instances of " +":class:`~datetime.datetime`, :class:`~datetime.date` and " +":class:`~datetime.time` pickled by Python 2." +msgstr "" + +#: ../../library/pickle.rst:419 +msgid "" +"If *buffers* is ``None`` (the default), then all data necessary for " +"deserialization must be contained in the pickle stream. This means that the" +" *buffer_callback* argument was ``None`` when a :class:`Pickler` was " +"instantiated (or when :func:`dump` or :func:`dumps` was called)." +msgstr "" + +#: ../../library/pickle.rst:424 +msgid "" +"If *buffers* is not ``None``, it should be an iterable of buffer-enabled " +"objects that is consumed each time the pickle stream references an " +":ref:`out-of-band ` buffer view. Such buffers have been given " +"in order to the *buffer_callback* of a Pickler object." +msgstr "" + +#: ../../library/pickle.rst:434 +msgid "" +"Read the pickled representation of an object from the open file object given" +" in the constructor, and return the reconstituted object hierarchy specified" +" therein. Bytes past the pickled representation of the object are ignored." +msgstr "" + +#: ../../library/pickle.rst:441 +msgid "Raise an :exc:`UnpicklingError` by default." +msgstr "" + +#: ../../library/pickle.rst:443 +msgid "" +"If defined, :meth:`persistent_load` should return the object specified by " +"the persistent ID *pid*. If an invalid persistent ID is encountered, an " +":exc:`UnpicklingError` should be raised." +msgstr "" + +#: ../../library/pickle.rst:451 +msgid "" +"Import *module* if necessary and return the object called *name* from it, " +"where the *module* and *name* arguments are :class:`str` objects. Note, " +"unlike its name suggests, :meth:`find_class` is also used for finding " +"functions." +msgstr "" + +#: ../../library/pickle.rst:456 +msgid "" +"Subclasses may override this to gain control over what type of objects and " +"how they can be loaded, potentially reducing security risks. Refer to " +":ref:`pickle-restrict` for details." +msgstr "" + +#: ../../library/pickle.rst:460 +msgid "" +"Raises an :ref:`auditing event ` ``pickle.find_class`` with " +"arguments ``module``, ``name``." +msgstr "" +"引發一個附帶引數 ``module``、``name`` 的\\ :ref:`稽核事件 ` " +"``pickle.find_class``。" + +#: ../../library/pickle.rst:464 +msgid "" +"A wrapper for a buffer representing picklable data. *buffer* must be a " +":ref:`buffer-providing ` object, such as a :term:`bytes-like " +"object` or a N-dimensional array." +msgstr "" + +#: ../../library/pickle.rst:468 +msgid "" +":class:`PickleBuffer` is itself a buffer provider, therefore it is possible " +"to pass it to other APIs expecting a buffer-providing object, such as " +":class:`memoryview`." +msgstr "" + +#: ../../library/pickle.rst:472 +msgid "" +":class:`PickleBuffer` objects can only be serialized using pickle protocol 5" +" or higher. They are eligible for :ref:`out-of-band serialization `." +msgstr "" + +#: ../../library/pickle.rst:480 +msgid "" +"Return a :class:`memoryview` of the memory area underlying this buffer. The " +"returned object is a one-dimensional, C-contiguous memoryview with format " +"``B`` (unsigned bytes). :exc:`BufferError` is raised if the buffer is " +"neither C- nor Fortran-contiguous." +msgstr "" + +#: ../../library/pickle.rst:487 +msgid "Release the underlying buffer exposed by the PickleBuffer object." +msgstr "" + +#: ../../library/pickle.rst:493 +msgid "What can be pickled and unpickled?" +msgstr "" + +#: ../../library/pickle.rst:495 +msgid "The following types can be pickled:" +msgstr "" + +#: ../../library/pickle.rst:497 +msgid "" +"built-in constants (``None``, ``True``, ``False``, ``Ellipsis``, and " +":data:`NotImplemented`);" +msgstr "" + +#: ../../library/pickle.rst:500 +msgid "integers, floating-point numbers, complex numbers;" +msgstr "" + +#: ../../library/pickle.rst:502 +msgid "strings, bytes, bytearrays;" +msgstr "" + +#: ../../library/pickle.rst:504 +msgid "" +"tuples, lists, sets, and dictionaries containing only picklable objects;" +msgstr "" + +#: ../../library/pickle.rst:506 +msgid "" +"functions (built-in and user-defined) accessible from the top level of a " +"module (using :keyword:`def`, not :keyword:`lambda`);" +msgstr "" + +#: ../../library/pickle.rst:509 +msgid "classes accessible from the top level of a module;" +msgstr "" + +#: ../../library/pickle.rst:511 +msgid "" +"instances of such classes whose the result of calling " +":meth:`~object.__getstate__` is picklable (see section :ref:`pickle-inst` " +"for details)." +msgstr "" + +#: ../../library/pickle.rst:514 +msgid "" +"Attempts to pickle unpicklable objects will raise the :exc:`PicklingError` " +"exception; when this happens, an unspecified number of bytes may have " +"already been written to the underlying file. Trying to pickle a highly " +"recursive data structure may exceed the maximum recursion depth, a " +":exc:`RecursionError` will be raised in this case. You can carefully raise " +"this limit with :func:`sys.setrecursionlimit`." +msgstr "" + +#: ../../library/pickle.rst:521 +msgid "" +"Note that functions (built-in and user-defined) are pickled by fully " +":term:`qualified name`, not by value. [#]_ This means that only the " +"function name is pickled, along with the name of the containing module and " +"classes. Neither the function's code, nor any of its function attributes " +"are pickled. Thus the defining module must be importable in the unpickling " +"environment, and the module must contain the named object, otherwise an " +"exception will be raised. [#]_" +msgstr "" + +#: ../../library/pickle.rst:528 +msgid "" +"Similarly, classes are pickled by fully qualified name, so the same " +"restrictions in the unpickling environment apply. Note that none of the " +"class's code or data is pickled, so in the following example the class " +"attribute ``attr`` is not restored in the unpickling environment::" +msgstr "" + +#: ../../library/pickle.rst:538 +msgid "" +"These restrictions are why picklable functions and classes must be defined " +"at the top level of a module." +msgstr "" + +#: ../../library/pickle.rst:541 +msgid "" +"Similarly, when class instances are pickled, their class's code and data are" +" not pickled along with them. Only the instance data are pickled. This is " +"done on purpose, so you can fix bugs in a class or add methods to the class " +"and still load objects that were created with an earlier version of the " +"class. If you plan to have long-lived objects that will see many versions " +"of a class, it may be worthwhile to put a version number in the objects so " +"that suitable conversions can be made by the class's " +":meth:`~object.__setstate__` method." +msgstr "" + +#: ../../library/pickle.rst:553 +msgid "Pickling Class Instances" +msgstr "" + +#: ../../library/pickle.rst:557 +msgid "" +"In this section, we describe the general mechanisms available to you to " +"define, customize, and control how class instances are pickled and " +"unpickled." +msgstr "" + +#: ../../library/pickle.rst:560 +msgid "" +"In most cases, no additional code is needed to make instances picklable. By" +" default, pickle will retrieve the class and the attributes of an instance " +"via introspection. When a class instance is unpickled, its " +":meth:`~object.__init__` method is usually *not* invoked. The default " +"behaviour first creates an uninitialized instance and then restores the " +"saved attributes. The following code shows an implementation of this " +"behaviour::" +msgstr "" + +#: ../../library/pickle.rst:575 +msgid "" +"Classes can alter the default behaviour by providing one or several special " +"methods:" +msgstr "" + +#: ../../library/pickle.rst:580 +msgid "" +"In protocols 2 and newer, classes that implements the " +":meth:`__getnewargs_ex__` method can dictate the values passed to the " +":meth:`__new__` method upon unpickling. The method must return a pair " +"``(args, kwargs)`` where *args* is a tuple of positional arguments and " +"*kwargs* a dictionary of named arguments for constructing the object. Those" +" will be passed to the :meth:`__new__` method upon unpickling." +msgstr "" + +#: ../../library/pickle.rst:588 +msgid "" +"You should implement this method if the :meth:`__new__` method of your class" +" requires keyword-only arguments. Otherwise, it is recommended for " +"compatibility to implement :meth:`__getnewargs__`." +msgstr "" + +#: ../../library/pickle.rst:592 +msgid ":meth:`__getnewargs_ex__` is now used in protocols 2 and 3." +msgstr "" + +#: ../../library/pickle.rst:598 +msgid "" +"This method serves a similar purpose as :meth:`__getnewargs_ex__`, but " +"supports only positional arguments. It must return a tuple of arguments " +"``args`` which will be passed to the :meth:`__new__` method upon unpickling." +msgstr "" + +#: ../../library/pickle.rst:602 +msgid "" +":meth:`__getnewargs__` will not be called if :meth:`__getnewargs_ex__` is " +"defined." +msgstr "" + +#: ../../library/pickle.rst:605 +msgid "" +"Before Python 3.6, :meth:`__getnewargs__` was called instead of " +":meth:`__getnewargs_ex__` in protocols 2 and 3." +msgstr "" + +#: ../../library/pickle.rst:612 +msgid "" +"Classes can further influence how their instances are pickled by overriding " +"the method :meth:`__getstate__`. It is called and the returned object is " +"pickled as the contents for the instance, instead of a default state. There " +"are several cases:" +msgstr "" + +#: ../../library/pickle.rst:617 +msgid "" +"For a class that has no instance :attr:`~object.__dict__` and no " +":attr:`~object.__slots__`, the default state is ``None``." +msgstr "" + +#: ../../library/pickle.rst:620 +msgid "" +"For a class that has an instance :attr:`~object.__dict__` and no " +":attr:`~object.__slots__`, the default state is ``self.__dict__``." +msgstr "" + +#: ../../library/pickle.rst:623 +msgid "" +"For a class that has an instance :attr:`~object.__dict__` and " +":attr:`~object.__slots__`, the default state is a tuple consisting of two " +"dictionaries: ``self.__dict__``, and a dictionary mapping slot names to " +"slot values. Only slots that have a value are included in the latter." +msgstr "" + +#: ../../library/pickle.rst:629 +msgid "" +"For a class that has :attr:`~object.__slots__` and no instance " +":attr:`~object.__dict__`, the default state is a tuple whose first item is " +"``None`` and whose second item is a dictionary mapping slot names to slot " +"values described in the previous bullet." +msgstr "" + +#: ../../library/pickle.rst:634 +msgid "" +"Added the default implementation of the ``__getstate__()`` method in the " +":class:`object` class." +msgstr "" + +#: ../../library/pickle.rst:641 +msgid "" +"Upon unpickling, if the class defines :meth:`__setstate__`, it is called " +"with the unpickled state. In that case, there is no requirement for the " +"state object to be a dictionary. Otherwise, the pickled state must be a " +"dictionary and its items are assigned to the new instance's dictionary." +msgstr "" + +#: ../../library/pickle.rst:648 +msgid "" +"If :meth:`__reduce__` returns a state with value ``None`` at pickling, the " +":meth:`__setstate__` method will not be called upon unpickling." +msgstr "" + +#: ../../library/pickle.rst:652 +msgid "" +"Refer to the section :ref:`pickle-state` for more information about how to " +"use the methods :meth:`~object.__getstate__` and " +":meth:`~object.__setstate__`." +msgstr "" + +#: ../../library/pickle.rst:657 +msgid "" +"At unpickling time, some methods like :meth:`~object.__getattr__`, " +":meth:`~object.__getattribute__`, or :meth:`~object.__setattr__` may be " +"called upon the instance. In case those methods rely on some internal " +"invariant being true, the type should implement :meth:`~object.__new__` to " +"establish such an invariant, as :meth:`~object.__init__` is not called when " +"unpickling an instance." +msgstr "" + +#: ../../library/pickle.rst:666 +msgid "" +"As we shall see, pickle does not use directly the methods described above. " +"In fact, these methods are part of the copy protocol which implements the " +":meth:`~object.__reduce__` special method. The copy protocol provides a " +"unified interface for retrieving the data necessary for pickling and copying" +" objects. [#]_" +msgstr "" + +#: ../../library/pickle.rst:672 +msgid "" +"Although powerful, implementing :meth:`~object.__reduce__` directly in your " +"classes is error prone. For this reason, class designers should use the " +"high-level interface (i.e., :meth:`~object.__getnewargs_ex__`, " +":meth:`~object.__getstate__` and :meth:`~object.__setstate__`) whenever " +"possible. We will show, however, cases where using :meth:`!__reduce__` is " +"the only option or leads to more efficient pickling or both." +msgstr "" + +#: ../../library/pickle.rst:681 +msgid "" +"The interface is currently defined as follows. The :meth:`__reduce__` " +"method takes no argument and shall return either a string or preferably a " +"tuple (the returned object is often referred to as the \"reduce value\")." +msgstr "" + +#: ../../library/pickle.rst:685 +msgid "" +"If a string is returned, the string should be interpreted as the name of a " +"global variable. It should be the object's local name relative to its " +"module; the pickle module searches the module namespace to determine the " +"object's module. This behaviour is typically useful for singletons." +msgstr "" + +#: ../../library/pickle.rst:690 +msgid "" +"When a tuple is returned, it must be between two and six items long. " +"Optional items can either be omitted, or ``None`` can be provided as their " +"value. The semantics of each item are in order:" +msgstr "" + +#: ../../library/pickle.rst:696 +msgid "" +"A callable object that will be called to create the initial version of the " +"object." +msgstr "" + +#: ../../library/pickle.rst:699 +msgid "" +"A tuple of arguments for the callable object. An empty tuple must be given " +"if the callable does not accept any argument." +msgstr "" + +#: ../../library/pickle.rst:702 +msgid "" +"Optionally, the object's state, which will be passed to the object's " +":meth:`__setstate__` method as previously described. If the object has no " +"such method then, the value must be a dictionary and it will be added to the" +" object's :attr:`~object.__dict__` attribute." +msgstr "" + +#: ../../library/pickle.rst:707 +msgid "" +"Optionally, an iterator (and not a sequence) yielding successive items. " +"These items will be appended to the object either using ``obj.append(item)``" +" or, in batch, using ``obj.extend(list_of_items)``. This is primarily used " +"for list subclasses, but may be used by other classes as long as they have " +":ref:`append and extend methods ` with the appropriate " +"signature. (Whether :meth:`!append` or :meth:`!extend` is used depends on " +"which pickle protocol version is used as well as the number of items to " +"append, so both must be supported.)" +msgstr "" + +#: ../../library/pickle.rst:717 +msgid "" +"Optionally, an iterator (not a sequence) yielding successive key-value " +"pairs. These items will be stored to the object using ``obj[key] = value``." +" This is primarily used for dictionary subclasses, but may be used by other" +" classes as long as they implement :meth:`__setitem__`." +msgstr "" + +#: ../../library/pickle.rst:722 +msgid "" +"Optionally, a callable with a ``(obj, state)`` signature. This callable " +"allows the user to programmatically control the state-updating behavior of a" +" specific object, instead of using ``obj``'s static :meth:`__setstate__` " +"method. If not ``None``, this callable will have priority over ``obj``'s " +":meth:`__setstate__`." +msgstr "" + +#: ../../library/pickle.rst:728 +msgid "The optional sixth tuple item, ``(obj, state)``, was added." +msgstr "" + +#: ../../library/pickle.rst:734 +msgid "" +"Alternatively, a :meth:`__reduce_ex__` method may be defined. The only " +"difference is this method should take a single integer argument, the " +"protocol version. When defined, pickle will prefer it over the " +":meth:`__reduce__` method. In addition, :meth:`__reduce__` automatically " +"becomes a synonym for the extended version. The main use for this method is" +" to provide backwards-compatible reduce values for older Python releases." +msgstr "" + +#: ../../library/pickle.rst:746 +msgid "Persistence of External Objects" +msgstr "" + +#: ../../library/pickle.rst:752 +msgid "" +"For the benefit of object persistence, the :mod:`pickle` module supports the" +" notion of a reference to an object outside the pickled data stream. Such " +"objects are referenced by a persistent ID, which should be either a string " +"of alphanumeric characters (for protocol 0) [#]_ or just an arbitrary object" +" (for any newer protocol)." +msgstr "" + +#: ../../library/pickle.rst:758 +msgid "" +"The resolution of such persistent IDs is not defined by the :mod:`pickle` " +"module; it will delegate this resolution to the user-defined methods on the " +"pickler and unpickler, :meth:`~Pickler.persistent_id` and " +":meth:`~Unpickler.persistent_load` respectively." +msgstr "" + +#: ../../library/pickle.rst:763 +msgid "" +"To pickle objects that have an external persistent ID, the pickler must have" +" a custom :meth:`~Pickler.persistent_id` method that takes an object as an " +"argument and returns either ``None`` or the persistent ID for that object. " +"When ``None`` is returned, the pickler simply pickles the object as normal. " +"When a persistent ID string is returned, the pickler will pickle that " +"object, along with a marker so that the unpickler will recognize it as a " +"persistent ID." +msgstr "" + +#: ../../library/pickle.rst:770 +msgid "" +"To unpickle external objects, the unpickler must have a custom " +":meth:`~Unpickler.persistent_load` method that takes a persistent ID object " +"and returns the referenced object." +msgstr "" + +#: ../../library/pickle.rst:774 +msgid "" +"Here is a comprehensive example presenting how persistent ID can be used to " +"pickle external objects by reference." +msgstr "" + +#: ../../library/pickle.rst:782 +msgid "Dispatch Tables" +msgstr "" + +#: ../../library/pickle.rst:784 +msgid "" +"If one wants to customize pickling of some classes without disturbing any " +"other code which depends on pickling, then one can create a pickler with a " +"private dispatch table." +msgstr "" + +#: ../../library/pickle.rst:788 +msgid "" +"The global dispatch table managed by the :mod:`copyreg` module is available " +"as :data:`!copyreg.dispatch_table`. Therefore, one may choose to use a " +"modified copy of :data:`!copyreg.dispatch_table` as a private dispatch " +"table." +msgstr "" + +#: ../../library/pickle.rst:793 +msgid "For example ::" +msgstr "舉例來說： ::" + +#: ../../library/pickle.rst:800 +msgid "" +"creates an instance of :class:`pickle.Pickler` with a private dispatch table" +" which handles the ``SomeClass`` class specially. Alternatively, the code " +"::" +msgstr "" + +#: ../../library/pickle.rst:810 +msgid "" +"does the same but all instances of ``MyPickler`` will by default share the " +"private dispatch table. On the other hand, the code ::" +msgstr "" + +#: ../../library/pickle.rst:817 +msgid "" +"modifies the global dispatch table shared by all users of the :mod:`copyreg`" +" module." +msgstr "" + +#: ../../library/pickle.rst:822 +msgid "Handling Stateful Objects" +msgstr "" + +#: ../../library/pickle.rst:828 +msgid "" +"Here's an example that shows how to modify pickling behavior for a class. " +"The :class:`!TextReader` class below opens a text file, and returns the line" +" number and line contents each time its :meth:`!readline` method is called. " +"If a :class:`!TextReader` instance is pickled, all attributes *except* the " +"file object member are saved. When the instance is unpickled, the file is " +"reopened, and reading resumes from the last location. The " +":meth:`!__setstate__` and :meth:`!__getstate__` methods are used to " +"implement this behavior. ::" +msgstr "" + +#: ../../library/pickle.rst:874 +msgid "A sample usage might be something like this::" +msgstr "" + +#: ../../library/pickle.rst:888 +msgid "Custom Reduction for Types, Functions, and Other Objects" +msgstr "" + +#: ../../library/pickle.rst:892 +msgid "" +"Sometimes, :attr:`~Pickler.dispatch_table` may not be flexible enough. In " +"particular we may want to customize pickling based on another criterion than" +" the object's type, or we may want to customize the pickling of functions " +"and classes." +msgstr "" + +#: ../../library/pickle.rst:897 +msgid "" +"For those cases, it is possible to subclass from the :class:`Pickler` class " +"and implement a :meth:`~Pickler.reducer_override` method. This method can " +"return an arbitrary reduction tuple (see :meth:`~object.__reduce__`). It can" +" alternatively return :data:`NotImplemented` to fallback to the traditional " +"behavior." +msgstr "" + +#: ../../library/pickle.rst:902 +msgid "" +"If both the :attr:`~Pickler.dispatch_table` and " +":meth:`~Pickler.reducer_override` are defined, then " +":meth:`~Pickler.reducer_override` method takes priority." +msgstr "" + +#: ../../library/pickle.rst:907 +msgid "" +"For performance reasons, :meth:`~Pickler.reducer_override` may not be called" +" for the following objects: ``None``, ``True``, ``False``, and exact " +"instances of :class:`int`, :class:`float`, :class:`bytes`, :class:`str`, " +":class:`dict`, :class:`set`, :class:`frozenset`, :class:`list` and " +":class:`tuple`." +msgstr "" + +#: ../../library/pickle.rst:913 +msgid "" +"Here is a simple example where we allow pickling and reconstructing a given " +"class::" +msgstr "" + +#: ../../library/pickle.rst:948 +msgid "Out-of-band Buffers" +msgstr "" + +#: ../../library/pickle.rst:952 +msgid "" +"In some contexts, the :mod:`pickle` module is used to transfer massive " +"amounts of data. Therefore, it can be important to minimize the number of " +"memory copies, to preserve performance and resource consumption. However, " +"normal operation of the :mod:`pickle` module, as it transforms a graph-like " +"structure of objects into a sequential stream of bytes, intrinsically " +"involves copying data to and from the pickle stream." +msgstr "" + +#: ../../library/pickle.rst:959 +msgid "" +"This constraint can be eschewed if both the *provider* (the implementation " +"of the object types to be transferred) and the *consumer* (the " +"implementation of the communications system) support the out-of-band " +"transfer facilities provided by pickle protocol 5 and higher." +msgstr "" + +#: ../../library/pickle.rst:965 +msgid "Provider API" +msgstr "" + +#: ../../library/pickle.rst:967 +msgid "" +"The large data objects to be pickled must implement a " +":meth:`~object.__reduce_ex__` method specialized for protocol 5 and higher, " +"which returns a :class:`PickleBuffer` instance (instead of e.g. a " +":class:`bytes` object) for any large data." +msgstr "" + +#: ../../library/pickle.rst:972 +msgid "" +"A :class:`PickleBuffer` object *signals* that the underlying buffer is " +"eligible for out-of-band data transfer. Those objects remain compatible " +"with normal usage of the :mod:`pickle` module. However, consumers can also " +"opt-in to tell :mod:`pickle` that they will handle those buffers by " +"themselves." +msgstr "" + +#: ../../library/pickle.rst:979 +msgid "Consumer API" +msgstr "" + +#: ../../library/pickle.rst:981 +msgid "" +"A communications system can enable custom handling of the " +":class:`PickleBuffer` objects generated when serializing an object graph." +msgstr "" + +#: ../../library/pickle.rst:984 +msgid "" +"On the sending side, it needs to pass a *buffer_callback* argument to " +":class:`Pickler` (or to the :func:`dump` or :func:`dumps` function), which " +"will be called with each :class:`PickleBuffer` generated while pickling the " +"object graph. Buffers accumulated by the *buffer_callback* will not see " +"their data copied into the pickle stream, only a cheap marker will be " +"inserted." +msgstr "" + +#: ../../library/pickle.rst:991 +msgid "" +"On the receiving side, it needs to pass a *buffers* argument to " +":class:`Unpickler` (or to the :func:`load` or :func:`loads` function), which" +" is an iterable of the buffers which were passed to *buffer_callback*. That " +"iterable should produce buffers in the same order as they were passed to " +"*buffer_callback*. Those buffers will provide the data expected by the " +"reconstructors of the objects whose pickling produced the original " +":class:`PickleBuffer` objects." +msgstr "" + +#: ../../library/pickle.rst:999 +msgid "" +"Between the sending side and the receiving side, the communications system " +"is free to implement its own transfer mechanism for out-of-band buffers. " +"Potential optimizations include the use of shared memory or datatype-" +"dependent compression." +msgstr "" + +#: ../../library/pickle.rst:1005 +msgid "Example" +msgstr "範例" + +#: ../../library/pickle.rst:1007 +msgid "" +"Here is a trivial example where we implement a :class:`bytearray` subclass " +"able to participate in out-of-band buffer pickling::" +msgstr "" + +#: ../../library/pickle.rst:1031 +msgid "" +"The reconstructor (the ``_reconstruct`` class method) returns the buffer's " +"providing object if it has the right type. This is an easy way to simulate " +"zero-copy behaviour on this toy example." +msgstr "" + +#: ../../library/pickle.rst:1035 +msgid "" +"On the consumer side, we can pickle those objects the usual way, which when " +"unserialized will give us a copy of the original object::" +msgstr "" + +#: ../../library/pickle.rst:1044 +msgid "" +"But if we pass a *buffer_callback* and then give back the accumulated " +"buffers when unserializing, we are able to get back the original object::" +msgstr "" + +#: ../../library/pickle.rst:1054 +msgid "" +"This example is limited by the fact that :class:`bytearray` allocates its " +"own memory: you cannot create a :class:`bytearray` instance that is backed " +"by another object's memory. However, third-party datatypes such as NumPy " +"arrays do not have this limitation, and allow use of zero-copy pickling (or " +"making as few copies as possible) when transferring between distinct " +"processes or systems." +msgstr "" + +#: ../../library/pickle.rst:1061 +msgid ":pep:`574` -- Pickle protocol 5 with out-of-band data" +msgstr "" + +#: ../../library/pickle.rst:1067 +msgid "Restricting Globals" +msgstr "" + +#: ../../library/pickle.rst:1072 +msgid "" +"By default, unpickling will import any class or function that it finds in " +"the pickle data. For many applications, this behaviour is unacceptable as " +"it permits the unpickler to import and invoke arbitrary code. Just consider" +" what this hand-crafted pickle data stream does when loaded::" +msgstr "" + +#: ../../library/pickle.rst:1082 +msgid "" +"In this example, the unpickler imports the :func:`os.system` function and " +"then apply the string argument \"echo hello world\". Although this example " +"is inoffensive, it is not difficult to imagine one that could damage your " +"system." +msgstr "" + +#: ../../library/pickle.rst:1086 +msgid "" +"For this reason, you may want to control what gets unpickled by customizing " +":meth:`Unpickler.find_class`. Unlike its name suggests, " +":meth:`Unpickler.find_class` is called whenever a global (i.e., a class or a" +" function) is requested. Thus it is possible to either completely forbid " +"globals or restrict them to a safe subset." +msgstr "" + +#: ../../library/pickle.rst:1092 +msgid "" +"Here is an example of an unpickler allowing only few safe classes from the " +":mod:`builtins` module to be loaded::" +msgstr "" + +#: ../../library/pickle.rst:1121 +msgid "A sample usage of our unpickler working as intended::" +msgstr "" + +#: ../../library/pickle.rst:1140 +msgid "" +"As our examples shows, you have to be careful with what you allow to be " +"unpickled. Therefore if security is a concern, you may want to consider " +"alternatives such as the marshalling API in :mod:`xmlrpc.client` or third-" +"party solutions." +msgstr "" + +#: ../../library/pickle.rst:1147 +msgid "Performance" +msgstr "" + +#: ../../library/pickle.rst:1149 +msgid "" +"Recent versions of the pickle protocol (from protocol 2 and upwards) feature" +" efficient binary encodings for several common features and built-in types. " +"Also, the :mod:`pickle` module has a transparent optimizer written in C." +msgstr "" + +#: ../../library/pickle.rst:1157 +msgid "Examples" +msgstr "範例" + +#: ../../library/pickle.rst:1159 +msgid "" +"For the simplest code, use the :func:`dump` and :func:`load` functions. ::" +msgstr "" + +#: ../../library/pickle.rst:1175 +msgid "The following example reads the resulting pickled data. ::" +msgstr "" + +#: ../../library/pickle.rst:1191 +msgid "Module :mod:`copyreg`" +msgstr ":mod:`copyreg` 模組" + +#: ../../library/pickle.rst:1192 +msgid "Pickle interface constructor registration for extension types." +msgstr "" + +#: ../../library/pickle.rst:1194 +msgid "Module :mod:`pickletools`" +msgstr ":mod:`pickletools` 模組" + +#: ../../library/pickle.rst:1195 +msgid "Tools for working with and analyzing pickled data." +msgstr "" + +#: ../../library/pickle.rst:1197 +msgid "Module :mod:`shelve`" +msgstr ":mod:`shelve` 模組" + +#: ../../library/pickle.rst:1198 +msgid "Indexed databases of objects; uses :mod:`pickle`." +msgstr "" + +#: ../../library/pickle.rst:1200 +msgid "Module :mod:`copy`" +msgstr ":mod:`copy` 模組" + +#: ../../library/pickle.rst:1201 +msgid "Shallow and deep object copying." +msgstr "" + +#: ../../library/pickle.rst:1203 +msgid "Module :mod:`marshal`" +msgstr ":mod:`marshal` 模組" + +#: ../../library/pickle.rst:1204 +msgid "High-performance serialization of built-in types." +msgstr "" + +#: ../../library/pickle.rst:1208 +msgid "Footnotes" +msgstr "註解" + +#: ../../library/pickle.rst:1209 +msgid "Don't confuse this with the :mod:`marshal` module" +msgstr "" + +#: ../../library/pickle.rst:1211 +msgid "" +"This is why :keyword:`lambda` functions cannot be pickled: all " +":keyword:`!lambda` functions share the same name: ````." +msgstr "" + +#: ../../library/pickle.rst:1214 +msgid "" +"The exception raised will likely be an :exc:`ImportError` or an " +":exc:`AttributeError` but it could be something else." +msgstr "" + +#: ../../library/pickle.rst:1217 +msgid "" +"The :mod:`copy` module uses this protocol for shallow and deep copying " +"operations." +msgstr "" + +#: ../../library/pickle.rst:1220 +msgid "" +"The limitation on alphanumeric characters is due to the fact that persistent" +" IDs in protocol 0 are delimited by the newline character. Therefore if any" +" kind of newline characters occurs in persistent IDs, the resulting pickled " +"data will become unreadable." +msgstr "" + +#: ../../library/pickle.rst:12 +msgid "persistence" +msgstr "persistence（持續性）" + +#: ../../library/pickle.rst:12 +msgid "persistent" +msgstr "persistent（持續）" + +#: ../../library/pickle.rst:12 +msgid "objects" +msgstr "objects（物件）" + +#: ../../library/pickle.rst:12 +msgid "serializing" +msgstr "serializing（序列化）" + +#: ../../library/pickle.rst:12 +msgid "marshalling" +msgstr "marshalling" + +#: ../../library/pickle.rst:12 +msgid "flattening" +msgstr "flattening（攤平）" + +#: ../../library/pickle.rst:12 +msgid "pickling" +msgstr "pickling" + +#: ../../library/pickle.rst:123 +msgid "External Data Representation" +msgstr "External Data Representation（外部資料表示法）" + +#: ../../library/pickle.rst:664 +msgid "copy" +msgstr "copy（複製）" + +#: ../../library/pickle.rst:664 +msgid "protocol" +msgstr "protocol（協定）" + +#: ../../library/pickle.rst:748 +msgid "persistent_id (pickle protocol)" +msgstr "persistent_id（pickle 協定）" + +#: ../../library/pickle.rst:748 +msgid "persistent_load (pickle protocol)" +msgstr "persistent_load（pickle 協定）" + +#: ../../library/pickle.rst:824 +msgid "__getstate__() (copy protocol)" +msgstr "__getstate__()（copy 協定）" + +#: ../../library/pickle.rst:824 +msgid "__setstate__() (copy protocol)" +msgstr "__setstate__()（copy 協定）" + +#: ../../library/pickle.rst:1069 +msgid "find_class() (pickle protocol)" +msgstr "find_class()（pickle 協定）" From de36d132e1e97439d76a4fafc157fbb402469f8f Mon Sep 17 00:00:00 2001 From: "Raynor@GullU" Date: Wed, 21 Aug 2024 00:09:01 +0800 Subject: [PATCH 04/17] docs(library/pickle.po): editing, up to line 462 --- library/pickle.po | 3114 +++++++++++++++++++++++---------------------- 1 file changed, 1572 insertions(+), 1542 deletions(-) diff --git a/library/pickle.po b/library/pickle.po index 95f0a47a95..8c05090630 100644 --- a/library/pickle.po +++ b/library/pickle.po @@ -1,1542 +1,1572 @@ -# Copyright (C) 2001-2024, Python Software Foundation -# This file is distributed under the same license as the Python package. -# -# Translators: -# Skylull, 2024 -msgid "" -msgstr "" -"Project-Id-Version: Python 3.12\n" -"Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2024-05-09 00:03+0000\n" -"PO-Revision-Date: 2018-05-23 16:07+0000\n" -"Last-Translator: Adrian Liaw \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" -"Plural-Forms: nplurals=1; plural=0;\n" - -#: ../../library/pickle.rst:2 -msgid ":mod:`!pickle` --- Python object serialization" -msgstr ":mod:`!pickle` --- Python 物件序列化" - -#: ../../library/pickle.rst:10 -msgid "**Source code:** :source:`Lib/pickle.py`" -msgstr "**原始碼：**\\ :source:`Lib/pickle.py`" - -# Skylull: 我對 `pickle` 的命名原因進行了簡單的搜尋，只找到一則討論 -# https://stackoverflow.com/questions/27324986/pickles-why-are-they-called- -# that -# 其中表示這名字很可能只是為了隨便找一個p開頭的單字、或原始開發人員的內部玩笑造成的約定俗成。也有人表示醃製黃瓜（pickle- -# ing）的目標就是保存和存放，所以取了這個名字。 -# 無論如何似乎沒有一個定論。 -# 因為不確定是否與醃漬的這個梗有關，我暫時選擇使用 `封裝` 與 `拆封` 作為譯文，大致保存那個把東西處裡後裝起來的感覺但又不至於太奇怪。 -# 唯一需要擔心的是是否有與 `encapsulation` （封裝，網路協定名詞）或 `package`（封包，網路協定名詞）搞混的可能。 -#: ../../library/pickle.rst:22 -msgid "" -"The :mod:`pickle` module implements binary protocols for serializing and de-" -"serializing a Python object structure. *\"Pickling\"* is the process " -"whereby a Python object hierarchy is converted into a byte stream, and " -"*\"unpickling\"* is the inverse operation, whereby a byte stream (from a " -":term:`binary file` or :term:`bytes-like object`) is converted back into an " -"object hierarchy. Pickling (and unpickling) is alternatively known as " -"\"serialization\", \"marshalling,\" [#]_ or \"flattening\"; however, to " -"avoid confusion, the terms used here are \"pickling\" and \"unpickling\"." -msgstr "" -":mod:`pickle` 模組實作的是一個在二進位層級上對 Python 物件進行序列化（serialize）或去序列化（de-" -"serialize）。*\"Pickling\"* 用於專門指摘將一個 Python 物件轉換為一個二進位串流的過程，*\"unpickling\"* " -"則相反，指的是將一個（來自 :term:`binary file` 或 :term:`bytes-like object` 的）二進位串流轉換回 " -"Python 物件的過程。Pickling（和 unpickling）的過程也可能被稱作 \"serialization\", " -"\"marshalling,\" [#]_ 或 " -"\"flattening\"。不過，為了避免混淆，本文件將統一稱作封裝（pickling）、拆封（unpickling）。" - -#: ../../library/pickle.rst:33 -msgid "The ``pickle`` module **is not secure**. Only unpickle data you trust." -msgstr "``pickle`` 模組**並不安全**，切記只拆封你信任的資料。" - -#: ../../library/pickle.rst:35 -msgid "" -"It is possible to construct malicious pickle data which will **execute " -"arbitrary code during unpickling**. Never unpickle data that could have come" -" from an untrusted source, or that could have been tampered with." -msgstr "" -"pickle 封包是有可能被建立來在拆封的時候**執行任意惡意程式碼**的。絕對不要拆封任何你無法信任其來源、或可能被修改過的 pickle 封包。" - -#: ../../library/pickle.rst:39 -msgid "" -"Consider signing data with :mod:`hmac` if you need to ensure that it has not" -" been tampered with." -msgstr "建議你可以使用 :mod:`hmac` 模組來簽署這個封包，以確保其未被修改過。" - -#: ../../library/pickle.rst:42 -msgid "" -"Safer serialization formats such as :mod:`json` may be more appropriate if " -"you are processing untrusted data. See :ref:`comparison-with-json`." -msgstr "" -"如果你在處理不受信任的資料，其他比較安全的序列化格式（例如 :mod:`json`）可能會更適合。請參照 See :ref:`comparison-" -"with-json` 的說明。" - -#: ../../library/pickle.rst:47 -msgid "Relationship to other Python modules" -msgstr "和其他 Python 模組的關係" - -#: ../../library/pickle.rst:50 -msgid "Comparison with ``marshal``" -msgstr "和 ``marshal`` 的比較" - -#: ../../library/pickle.rst:52 -msgid "" -"Python has a more primitive serialization module called :mod:`marshal`, but " -"in general :mod:`pickle` should always be the preferred way to serialize " -"Python objects. :mod:`marshal` exists primarily to support Python's " -":file:`.pyc` files." -msgstr "" -"Python 有另一個比較原始的序列化模組叫 :mod:`marshal`，不過其設計目的是為了支援 Python 的預編譯功能 " -":file:`.pyc` 運作。總地來說，沒事不要用 :mod:`marshal`。" - -#: ../../library/pickle.rst:57 -msgid "" -"The :mod:`pickle` module differs from :mod:`marshal` in several significant " -"ways:" -msgstr ":mod:`pickle` 和 :mod:`marshal` 有幾個明顯不同的地方：" - -#: ../../library/pickle.rst:59 -msgid "" -"The :mod:`pickle` module keeps track of the objects it has already " -"serialized, so that later references to the same object won't be serialized " -"again. :mod:`marshal` doesn't do this." -msgstr "" -":mod:`pickle` 會記住哪些物件已經被序列化過了，稍後再次參照到這個物件的時候才不會進行重複的序列化。:mod:`marshal` " -"沒有這個功能。" - -#: ../../library/pickle.rst:63 -msgid "" -"This has implications both for recursive objects and object sharing. " -"Recursive objects are objects that contain references to themselves. These " -"are not handled by marshal, and in fact, attempting to marshal recursive " -"objects will crash your Python interpreter. Object sharing happens when " -"there are multiple references to the same object in different places in the " -"object hierarchy being serialized. :mod:`pickle` stores such objects only " -"once, and ensures that all other references point to the master copy. " -"Shared objects remain shared, which can be very important for mutable " -"objects." -msgstr "" -"這對遞迴物件和物件共用都有影響。遞迴物件是指包含自我參照的物件。這些情況在 marshal 模組中不會被處理，若嘗試使用 marshal " -"處理遞迴物件會導致 Python 直譯器崩潰。物件共用發生在序列化的物件階層中，不同位置對同一物件有多個參照時。:mod:`pickle` " -"只會儲存這個被參照的物件一次，並確保所有其他參照指向這個主要的版本。共用的物件會保持共用，這對於可變（mutable）物件來說非常重要。" - -#: ../../library/pickle.rst:72 -msgid "" -":mod:`marshal` cannot be used to serialize user-defined classes and their " -"instances. :mod:`pickle` can save and restore class instances " -"transparently, however the class definition must be importable and live in " -"the same module as when the object was stored." -msgstr "" -":mod:`marshal` 無法序列化使用者自訂的類別和的實例。:mod:`pickle` " -"則可以讓使用者儲存並還原自訂的類別實例，前提是儲存時該類別的定義存在於與要被儲存的物件所在的模組中、且可以被引入（import）。" - -#: ../../library/pickle.rst:77 -msgid "" -"The :mod:`marshal` serialization format is not guaranteed to be portable " -"across Python versions. Because its primary job in life is to support " -":file:`.pyc` files, the Python implementers reserve the right to change the " -"serialization format in non-backwards compatible ways should the need arise." -" The :mod:`pickle` serialization format is guaranteed to be backwards " -"compatible across Python releases provided a compatible pickle protocol is " -"chosen and pickling and unpickling code deals with Python 2 to Python 3 type" -" differences if your data is crossing that unique breaking change language " -"boundary." -msgstr "" -":mod:`marshal` 序列化格式無法保證能在不同版本的 Python 之間移植。因為其主要的作用是支援 :file:`.pyc` " -"檔案的運作，Python 的實作人員會在需要時實作無法前向相容的序列化方式。但只要選擇了相容的 pickle 協定，且處理了 Python 2 和 " -"Python 3 之間的資料類型差異，:mod:`pickle` 序列化協定能保證在不同 Python 版本間的相容性。" - -#: ../../library/pickle.rst:90 -msgid "Comparison with ``json``" -msgstr "和 ``json`` 的比較" - -#: ../../library/pickle.rst:92 -msgid "" -"There are fundamental differences between the pickle protocols and `JSON " -"(JavaScript Object Notation) `_:" -msgstr "" -"pickle 協定和 `JSON (JavaScript Object Notation) `_ " -"有一些根本上的不同：" - -#: ../../library/pickle.rst:95 -msgid "" -"JSON is a text serialization format (it outputs unicode text, although most " -"of the time it is then encoded to ``utf-8``), while pickle is a binary " -"serialization format;" -msgstr "" -"JSON 以文字形式作為序列化的輸出（輸出 unicode 文字，但大多數又會被編碼為 ``UTF-8``），而 pickle " -"則是以二進位形式作為序列化的輸出；" - -#: ../../library/pickle.rst:99 -msgid "JSON is human-readable, while pickle is not;" -msgstr "JSON 是人類可讀的，而 pickle 則無法；" - -#: ../../library/pickle.rst:101 -msgid "" -"JSON is interoperable and widely used outside of the Python ecosystem, while" -" pickle is Python-specific;" -msgstr "" -"JSON 具有高互通性（interoperability）且在 Python 以外的環境也被大量利用，但 pickle 只能在 Python 內使用。" - -# Skylull: introspection, introspection facilities -# https://zh.wikipedia.org/wiki/%E5%86%85%E7%9C%81_(%E8%AE%A1%E7%AE%97%E6%9C%BA%E7%A7%91%E5%AD%A6) -# https://book.pythontips.com/en/latest/object_introspection.html -# https://www.geeksforgeeks.org/code-introspection-in-python/ -#: ../../library/pickle.rst:104 -msgid "" -"JSON, by default, can only represent a subset of the Python built-in types, " -"and no custom classes; pickle can represent an extremely large number of " -"Python types (many of them automatically, by clever usage of Python's " -"introspection facilities; complex cases can be tackled by implementing " -":ref:`specific object APIs `);" -msgstr "" -"預設狀態下的 JSON 只能紀錄一小部份的 Python 內建型別，且無法紀錄自訂類別；但透過 Python 的自省功能，pickle " -"可以紀錄絕大多數的 Python 型別（其他比較複雜的狀況也可以透過實作 :ref:`specific object APIs ` 來解決）；" - -#: ../../library/pickle.rst:110 -msgid "" -"Unlike pickle, deserializing untrusted JSON does not in itself create an " -"arbitrary code execution vulnerability." -msgstr "去序列化不安全的 JSON 不會產生任意程式執行的風險，但去序列化不安全的 pickle 會。" - -#: ../../library/pickle.rst:114 -msgid "" -"The :mod:`json` module: a standard library module allowing JSON " -"serialization and deserialization." -msgstr ":mod:`json` module: 是標準函式庫的一部分，可讓使用者進行 JSON 的序列化與去序列化。" - -#: ../../library/pickle.rst:121 -msgid "Data stream format" -msgstr "資料串流格式" - -#: ../../library/pickle.rst:126 -msgid "" -"The data format used by :mod:`pickle` is Python-specific. This has the " -"advantage that there are no restrictions imposed by external standards such " -"as JSON or XDR (which can't represent pointer sharing); however it means " -"that non-Python programs may not be able to reconstruct pickled Python " -"objects." -msgstr "" -":mod:`pickle` 使用的資料格式是針對 Python 而設計的。好處是他不會受到外部標準（像是 JSON 或 XDR，而 XDR " -"無法紀錄指標共用）的限制；不過這也代表其他不是 Python 的程式可能無法重建 pickle 封裝的 Python 物件。" - -#: ../../library/pickle.rst:131 -msgid "" -"By default, the :mod:`pickle` data format uses a relatively compact binary " -"representation. If you need optimal size characteristics, you can " -"efficiently :doc:`compress ` pickled data." -msgstr "" -"以預設設定來說，:mod:`pickle` 使用相對緊湊的二進位形式來儲存資料。如果你需要盡可能地縮小檔案大小，你可以\\\\ :doc:`壓縮 " -"`\\\\ 封裝的資料。" - -#: ../../library/pickle.rst:135 -msgid "" -"The module :mod:`pickletools` contains tools for analyzing data streams " -"generated by :mod:`pickle`. :mod:`pickletools` source code has extensive " -"comments about opcodes used by pickle protocols." -msgstr "" -":mod:`pickletools` 含有工具可分析 :mod:`pickle` 所產生的資料流。:mod:`pickletools` " -"的源始碼詳細地記載了所有 pickle 協定的操作碼（opcode）。" - -#: ../../library/pickle.rst:139 -msgid "" -"There are currently 6 different protocols which can be used for pickling. " -"The higher the protocol used, the more recent the version of Python needed " -"to read the pickle produced." -msgstr "" -"截至目前為止，共有六種不同版本的協定可用於封裝 pickle。數字越大版本代表你需要使用越新的 Python 版本來拆封相應的 pickle 封裝。" - -#: ../../library/pickle.rst:143 -msgid "" -"Protocol version 0 is the original \"human-readable\" protocol and is " -"backwards compatible with earlier versions of Python." -msgstr "版本 0 的協定是最初「人類可讀」的版本，且可以向前支援早期版本的 Python。" - -#: ../../library/pickle.rst:146 -msgid "" -"Protocol version 1 is an old binary format which is also compatible with " -"earlier versions of Python." -msgstr "版本 1 的協定使用舊的二進位格式，一樣能向前支援早期版本的 Python。" - -#: ../../library/pickle.rst:149 -msgid "" -"Protocol version 2 was introduced in Python 2.3. It provides much more " -"efficient pickling of :term:`new-style classes `. Refer to" -" :pep:`307` for information about improvements brought by protocol 2." -msgstr "" -"版本 2 的協定在 Python 2.3 中初次被引入。其可提供更高效率的 :term:`new-style classes ` 封裝過程。請參閱 :pep:`307` 以了解版本 2 帶來的改進。" - -#: ../../library/pickle.rst:153 -msgid "" -"Protocol version 3 was added in Python 3.0. It has explicit support for " -":class:`bytes` objects and cannot be unpickled by Python 2.x. This was the " -"default protocol in Python 3.0--3.7." -msgstr "" -"版本 3 的協定在 Python 3.0 被新增。現在能支援封裝 :class:`bytes` 的物件且無法被 2.x 版本的 Python 拆封。在 " -"3.0～3.7 的 Python 預設使用 3 版協定。" - -#: ../../library/pickle.rst:157 -msgid "" -"Protocol version 4 was added in Python 3.4. It adds support for very large " -"objects, pickling more kinds of objects, and some data format optimizations." -" It is the default protocol starting with Python 3.8. Refer to :pep:`3154` " -"for information about improvements brought by protocol 4." -msgstr "" -"版本 4 的協定在 Python 3.4 被新增。現在能支援超大物件的封裝、更多種型別的物件以及針對部份資料格式的儲存進行最佳化。從 Python " -"3.8 起，預設使用第 4 版協定。請參閱 :pep:`3154` 以了解第 4 版協定改進的細節。" - -#: ../../library/pickle.rst:163 -msgid "" -"Protocol version 5 was added in Python 3.8. It adds support for out-of-band" -" data and speedup for in-band data. Refer to :pep:`574` for information " -"about improvements brought by protocol 5." -msgstr "" -"版本 5 的協定在 Python 3.8 被新增。現在能支援帶外資料（Out-of-band data）並加速帶內資料的處理速度。請參閱 " -":pep:`574` 以了解第 5 版協定改進的細節。" - -#: ../../library/pickle.rst:168 -msgid "" -"Serialization is a more primitive notion than persistence; although " -":mod:`pickle` reads and writes file objects, it does not handle the issue of" -" naming persistent objects, nor the (even more complicated) issue of " -"concurrent access to persistent objects. The :mod:`pickle` module can " -"transform a complex object into a byte stream and it can transform the byte " -"stream into an object with the same internal structure. Perhaps the most " -"obvious thing to do with these byte streams is to write them onto a file, " -"but it is also conceivable to send them across a network or store them in a " -"database. The :mod:`shelve` module provides a simple interface to pickle " -"and unpickle objects on DBM-style database files." -msgstr "" -"資料序列化是一個比資料持久化更早出現的概念；雖然 :mod:`pickle` " -"可以讀寫檔案物件，但它並不處理命名持久物件的問題，也不處理對持久物件的並行存取、一個更棘手的問題。:mod:`pickle` " -"模組可以將複雜物件轉換成位元組串流，也可以將位元組串流轉換回具有相同原始內部結構的物件。對這些位元組串流最常見的處理方式是將它們寫入檔案中，但也可以將它們透過網路傳送或儲存在一個資料庫中。:mod:`shelve`" -" 模組提供了一個簡單的介面來讓使用者在 DBM 風格的資料庫檔案中對物件進行封裝和拆封的操作。" - -#: ../../library/pickle.rst:181 -msgid "Module Interface" -msgstr "模組介面" - -#: ../../library/pickle.rst:183 -msgid "" -"To serialize an object hierarchy, you simply call the :func:`dumps` " -"function. Similarly, to de-serialize a data stream, you call the " -":func:`loads` function. However, if you want more control over serialization" -" and de-serialization, you can create a :class:`Pickler` or an " -":class:`Unpickler` object, respectively." -msgstr "" -"想要序列化一個物件，你只需要呼叫 :func:`dumps` 函數。而當你想要去序列化一個資料流時，你只需要呼叫 :func:`loads` " -"即可。不過，若你希望能各自對序列化和去序列化的過程中有更多的掌控度，你可以自訂一個 :class:`Pickler` 或 " -":class:`Unpickler` 物件。" - -#: ../../library/pickle.rst:188 -msgid "The :mod:`pickle` module provides the following constants:" -msgstr ":mod:`pickle` 模組提供以下常數：" - -#: ../../library/pickle.rst:193 -msgid "" -"An integer, the highest :ref:`protocol version ` " -"available. This value can be passed as a *protocol* value to functions " -":func:`dump` and :func:`dumps` as well as the :class:`Pickler` constructor." -msgstr "" -"一個整數，表示可使用的最高\\\\ :ref:`協定版本 `。這個值可作為 *protocol* 的數值傳給 " -":func:`dump` 和 :func:`dumps` 函數以及 :class:`Pickler` 建構式。" - -#: ../../library/pickle.rst:200 -msgid "" -"An integer, the default :ref:`protocol version ` used for " -"pickling. May be less than :data:`HIGHEST_PROTOCOL`. Currently the default" -" protocol is 4, first introduced in Python 3.4 and incompatible with " -"previous versions." -msgstr "" -"一個整數，指示用於序列化的預設\\\\ :ref:`協定版本 `。有可能小於 " -":data:`HIGHEST_PROTOCOL`。目前的預設協定版本為 4，是在 Python 3.4 中首次引入的，且與先前版本不相容。" - -#: ../../library/pickle.rst:207 -msgid "The default protocol is 3." -msgstr "預設協定版本為 3。" - -#: ../../library/pickle.rst:211 -msgid "The default protocol is 4." -msgstr "預設協定版本為 4。" - -#: ../../library/pickle.rst:213 -msgid "" -"The :mod:`pickle` module provides the following functions to make the " -"pickling process more convenient:" -msgstr ":mod:`pickle` 模組提供下列函數來簡化封裝的過程：" - -#: ../../library/pickle.rst:218 -msgid "" -"Write the pickled representation of the object *obj* to the open :term:`file" -" object` *file*. This is equivalent to ``Pickler(file, " -"protocol).dump(obj)``." -msgstr "" - -#: ../../library/pickle.rst:222 -msgid "" -"Arguments *file*, *protocol*, *fix_imports* and *buffer_callback* have the " -"same meaning as in the :class:`Pickler` constructor." -msgstr "" - -#: ../../library/pickle.rst:225 ../../library/pickle.rst:236 -#: ../../library/pickle.rst:328 -msgid "The *buffer_callback* argument was added." -msgstr "新增 *buffer_callback* 引數。" - -#: ../../library/pickle.rst:230 -msgid "" -"Return the pickled representation of the object *obj* as a :class:`bytes` " -"object, instead of writing it to a file." -msgstr "" - -#: ../../library/pickle.rst:233 -msgid "" -"Arguments *protocol*, *fix_imports* and *buffer_callback* have the same " -"meaning as in the :class:`Pickler` constructor." -msgstr "" - -#: ../../library/pickle.rst:241 -msgid "" -"Read the pickled representation of an object from the open :term:`file " -"object` *file* and return the reconstituted object hierarchy specified " -"therein. This is equivalent to ``Unpickler(file).load()``." -msgstr "" - -#: ../../library/pickle.rst:245 ../../library/pickle.rst:260 -msgid "" -"The protocol version of the pickle is detected automatically, so no protocol" -" argument is needed. Bytes past the pickled representation of the object " -"are ignored." -msgstr "" - -#: ../../library/pickle.rst:249 -msgid "" -"Arguments *file*, *fix_imports*, *encoding*, *errors*, *strict* and " -"*buffers* have the same meaning as in the :class:`Unpickler` constructor." -msgstr "" - -#: ../../library/pickle.rst:252 ../../library/pickle.rst:267 -#: ../../library/pickle.rst:429 -msgid "The *buffers* argument was added." -msgstr "新增 *buffer* 引數。" - -#: ../../library/pickle.rst:257 -msgid "" -"Return the reconstituted object hierarchy of the pickled representation " -"*data* of an object. *data* must be a :term:`bytes-like object`." -msgstr "" - -#: ../../library/pickle.rst:264 -msgid "" -"Arguments *fix_imports*, *encoding*, *errors*, *strict* and *buffers* have " -"the same meaning as in the :class:`Unpickler` constructor." -msgstr "" - -#: ../../library/pickle.rst:271 -msgid "The :mod:`pickle` module defines three exceptions:" -msgstr "" - -#: ../../library/pickle.rst:275 -msgid "" -"Common base class for the other pickling exceptions. It inherits from " -":exc:`Exception`." -msgstr "" - -#: ../../library/pickle.rst:280 -msgid "" -"Error raised when an unpicklable object is encountered by :class:`Pickler`. " -"It inherits from :exc:`PickleError`." -msgstr "" - -#: ../../library/pickle.rst:283 -msgid "" -"Refer to :ref:`pickle-picklable` to learn what kinds of objects can be " -"pickled." -msgstr "" - -#: ../../library/pickle.rst:288 -msgid "" -"Error raised when there is a problem unpickling an object, such as a data " -"corruption or a security violation. It inherits from :exc:`PickleError`." -msgstr "" - -#: ../../library/pickle.rst:291 -msgid "" -"Note that other exceptions may also be raised during unpickling, including " -"(but not necessarily limited to) AttributeError, EOFError, ImportError, and " -"IndexError." -msgstr "" - -#: ../../library/pickle.rst:296 -msgid "" -"The :mod:`pickle` module exports three classes, :class:`Pickler`, " -":class:`Unpickler` and :class:`PickleBuffer`:" -msgstr "" - -#: ../../library/pickle.rst:301 -msgid "This takes a binary file for writing a pickle data stream." -msgstr "" - -#: ../../library/pickle.rst:303 -msgid "" -"The optional *protocol* argument, an integer, tells the pickler to use the " -"given protocol; supported protocols are 0 to :data:`HIGHEST_PROTOCOL`. If " -"not specified, the default is :data:`DEFAULT_PROTOCOL`. If a negative " -"number is specified, :data:`HIGHEST_PROTOCOL` is selected." -msgstr "" - -#: ../../library/pickle.rst:308 -msgid "" -"The *file* argument must have a write() method that accepts a single bytes " -"argument. It can thus be an on-disk file opened for binary writing, an " -":class:`io.BytesIO` instance, or any other custom object that meets this " -"interface." -msgstr "" - -#: ../../library/pickle.rst:313 -msgid "" -"If *fix_imports* is true and *protocol* is less than 3, pickle will try to " -"map the new Python 3 names to the old module names used in Python 2, so that" -" the pickle data stream is readable with Python 2." -msgstr "" - -#: ../../library/pickle.rst:317 -msgid "" -"If *buffer_callback* is ``None`` (the default), buffer views are serialized " -"into *file* as part of the pickle stream." -msgstr "" - -#: ../../library/pickle.rst:320 -msgid "" -"If *buffer_callback* is not ``None``, then it can be called any number of " -"times with a buffer view. If the callback returns a false value (such as " -"``None``), the given buffer is :ref:`out-of-band `; otherwise " -"the buffer is serialized in-band, i.e. inside the pickle stream." -msgstr "" - -#: ../../library/pickle.rst:325 -msgid "" -"It is an error if *buffer_callback* is not ``None`` and *protocol* is " -"``None`` or smaller than 5." -msgstr "" - -#: ../../library/pickle.rst:333 -msgid "" -"Write the pickled representation of *obj* to the open file object given in " -"the constructor." -msgstr "" - -#: ../../library/pickle.rst:338 -msgid "Do nothing by default. This exists so a subclass can override it." -msgstr "" - -#: ../../library/pickle.rst:340 -msgid "" -"If :meth:`persistent_id` returns ``None``, *obj* is pickled as usual. Any " -"other value causes :class:`Pickler` to emit the returned value as a " -"persistent ID for *obj*. The meaning of this persistent ID should be " -"defined by :meth:`Unpickler.persistent_load`. Note that the value returned " -"by :meth:`persistent_id` cannot itself have a persistent ID." -msgstr "" - -#: ../../library/pickle.rst:346 ../../library/pickle.rst:447 -msgid "See :ref:`pickle-persistent` for details and examples of uses." -msgstr "關於細節與用法範例請見 :ref:`pickle-persistent`。" - -#: ../../library/pickle.rst:350 -msgid "" -"A pickler object's dispatch table is a registry of *reduction functions* of " -"the kind which can be declared using :func:`copyreg.pickle`. It is a " -"mapping whose keys are classes and whose values are reduction functions. A " -"reduction function takes a single argument of the associated class and " -"should conform to the same interface as a :meth:`~object.__reduce__` method." -msgstr "" - -#: ../../library/pickle.rst:358 -msgid "" -"By default, a pickler object will not have a :attr:`dispatch_table` " -"attribute, and it will instead use the global dispatch table managed by the " -":mod:`copyreg` module. However, to customize the pickling for a specific " -"pickler object one can set the :attr:`dispatch_table` attribute to a dict-" -"like object. Alternatively, if a subclass of :class:`Pickler` has a " -":attr:`dispatch_table` attribute then this will be used as the default " -"dispatch table for instances of that class." -msgstr "" - -#: ../../library/pickle.rst:367 -msgid "See :ref:`pickle-dispatch` for usage examples." -msgstr "關於用法範例請見 :ref:`pickle-dispatch`。" - -#: ../../library/pickle.rst:373 -msgid "" -"Special reducer that can be defined in :class:`Pickler` subclasses. This " -"method has priority over any reducer in the :attr:`dispatch_table`. It " -"should conform to the same interface as a :meth:`~object.__reduce__` method," -" and can optionally return :data:`NotImplemented` to fallback on " -":attr:`dispatch_table`-registered reducers to pickle ``obj``." -msgstr "" - -#: ../../library/pickle.rst:379 -msgid "For a detailed example, see :ref:`reducer_override`." -msgstr "" - -#: ../../library/pickle.rst:385 -msgid "" -"Deprecated. Enable fast mode if set to a true value. The fast mode disables" -" the usage of memo, therefore speeding the pickling process by not " -"generating superfluous PUT opcodes. It should not be used with self-" -"referential objects, doing otherwise will cause :class:`Pickler` to recurse " -"infinitely." -msgstr "" - -#: ../../library/pickle.rst:391 -msgid "Use :func:`pickletools.optimize` if you need more compact pickles." -msgstr "" - -#: ../../library/pickle.rst:396 -msgid "This takes a binary file for reading a pickle data stream." -msgstr "" - -#: ../../library/pickle.rst:398 -msgid "" -"The protocol version of the pickle is detected automatically, so no protocol" -" argument is needed." -msgstr "" - -#: ../../library/pickle.rst:401 -msgid "" -"The argument *file* must have three methods, a read() method that takes an " -"integer argument, a readinto() method that takes a buffer argument and a " -"readline() method that requires no arguments, as in the " -":class:`io.BufferedIOBase` interface. Thus *file* can be an on-disk file " -"opened for binary reading, an :class:`io.BytesIO` object, or any other " -"custom object that meets this interface." -msgstr "" - -#: ../../library/pickle.rst:408 -msgid "" -"The optional arguments *fix_imports*, *encoding* and *errors* are used to " -"control compatibility support for pickle stream generated by Python 2. If " -"*fix_imports* is true, pickle will try to map the old Python 2 names to the " -"new names used in Python 3. The *encoding* and *errors* tell pickle how to " -"decode 8-bit string instances pickled by Python 2; these default to 'ASCII' " -"and 'strict', respectively. The *encoding* can be 'bytes' to read these " -"8-bit string instances as bytes objects. Using ``encoding='latin1'`` is " -"required for unpickling NumPy arrays and instances of " -":class:`~datetime.datetime`, :class:`~datetime.date` and " -":class:`~datetime.time` pickled by Python 2." -msgstr "" - -#: ../../library/pickle.rst:419 -msgid "" -"If *buffers* is ``None`` (the default), then all data necessary for " -"deserialization must be contained in the pickle stream. This means that the" -" *buffer_callback* argument was ``None`` when a :class:`Pickler` was " -"instantiated (or when :func:`dump` or :func:`dumps` was called)." -msgstr "" - -#: ../../library/pickle.rst:424 -msgid "" -"If *buffers* is not ``None``, it should be an iterable of buffer-enabled " -"objects that is consumed each time the pickle stream references an " -":ref:`out-of-band ` buffer view. Such buffers have been given " -"in order to the *buffer_callback* of a Pickler object." -msgstr "" - -#: ../../library/pickle.rst:434 -msgid "" -"Read the pickled representation of an object from the open file object given" -" in the constructor, and return the reconstituted object hierarchy specified" -" therein. Bytes past the pickled representation of the object are ignored." -msgstr "" - -#: ../../library/pickle.rst:441 -msgid "Raise an :exc:`UnpicklingError` by default." -msgstr "" - -#: ../../library/pickle.rst:443 -msgid "" -"If defined, :meth:`persistent_load` should return the object specified by " -"the persistent ID *pid*. If an invalid persistent ID is encountered, an " -":exc:`UnpicklingError` should be raised." -msgstr "" - -#: ../../library/pickle.rst:451 -msgid "" -"Import *module* if necessary and return the object called *name* from it, " -"where the *module* and *name* arguments are :class:`str` objects. Note, " -"unlike its name suggests, :meth:`find_class` is also used for finding " -"functions." -msgstr "" - -#: ../../library/pickle.rst:456 -msgid "" -"Subclasses may override this to gain control over what type of objects and " -"how they can be loaded, potentially reducing security risks. Refer to " -":ref:`pickle-restrict` for details." -msgstr "" - -#: ../../library/pickle.rst:460 -msgid "" -"Raises an :ref:`auditing event ` ``pickle.find_class`` with " -"arguments ``module``, ``name``." -msgstr "" -"引發一個附帶引數 ``module``、``name`` 的\\ :ref:`稽核事件 ` " -"``pickle.find_class``。" - -#: ../../library/pickle.rst:464 -msgid "" -"A wrapper for a buffer representing picklable data. *buffer* must be a " -":ref:`buffer-providing ` object, such as a :term:`bytes-like " -"object` or a N-dimensional array." -msgstr "" - -#: ../../library/pickle.rst:468 -msgid "" -":class:`PickleBuffer` is itself a buffer provider, therefore it is possible " -"to pass it to other APIs expecting a buffer-providing object, such as " -":class:`memoryview`." -msgstr "" - -#: ../../library/pickle.rst:472 -msgid "" -":class:`PickleBuffer` objects can only be serialized using pickle protocol 5" -" or higher. They are eligible for :ref:`out-of-band serialization `." -msgstr "" - -#: ../../library/pickle.rst:480 -msgid "" -"Return a :class:`memoryview` of the memory area underlying this buffer. The " -"returned object is a one-dimensional, C-contiguous memoryview with format " -"``B`` (unsigned bytes). :exc:`BufferError` is raised if the buffer is " -"neither C- nor Fortran-contiguous." -msgstr "" - -#: ../../library/pickle.rst:487 -msgid "Release the underlying buffer exposed by the PickleBuffer object." -msgstr "" - -#: ../../library/pickle.rst:493 -msgid "What can be pickled and unpickled?" -msgstr "" - -#: ../../library/pickle.rst:495 -msgid "The following types can be pickled:" -msgstr "" - -#: ../../library/pickle.rst:497 -msgid "" -"built-in constants (``None``, ``True``, ``False``, ``Ellipsis``, and " -":data:`NotImplemented`);" -msgstr "" - -#: ../../library/pickle.rst:500 -msgid "integers, floating-point numbers, complex numbers;" -msgstr "" - -#: ../../library/pickle.rst:502 -msgid "strings, bytes, bytearrays;" -msgstr "" - -#: ../../library/pickle.rst:504 -msgid "" -"tuples, lists, sets, and dictionaries containing only picklable objects;" -msgstr "" - -#: ../../library/pickle.rst:506 -msgid "" -"functions (built-in and user-defined) accessible from the top level of a " -"module (using :keyword:`def`, not :keyword:`lambda`);" -msgstr "" - -#: ../../library/pickle.rst:509 -msgid "classes accessible from the top level of a module;" -msgstr "" - -#: ../../library/pickle.rst:511 -msgid "" -"instances of such classes whose the result of calling " -":meth:`~object.__getstate__` is picklable (see section :ref:`pickle-inst` " -"for details)." -msgstr "" - -#: ../../library/pickle.rst:514 -msgid "" -"Attempts to pickle unpicklable objects will raise the :exc:`PicklingError` " -"exception; when this happens, an unspecified number of bytes may have " -"already been written to the underlying file. Trying to pickle a highly " -"recursive data structure may exceed the maximum recursion depth, a " -":exc:`RecursionError` will be raised in this case. You can carefully raise " -"this limit with :func:`sys.setrecursionlimit`." -msgstr "" - -#: ../../library/pickle.rst:521 -msgid "" -"Note that functions (built-in and user-defined) are pickled by fully " -":term:`qualified name`, not by value. [#]_ This means that only the " -"function name is pickled, along with the name of the containing module and " -"classes. Neither the function's code, nor any of its function attributes " -"are pickled. Thus the defining module must be importable in the unpickling " -"environment, and the module must contain the named object, otherwise an " -"exception will be raised. [#]_" -msgstr "" - -#: ../../library/pickle.rst:528 -msgid "" -"Similarly, classes are pickled by fully qualified name, so the same " -"restrictions in the unpickling environment apply. Note that none of the " -"class's code or data is pickled, so in the following example the class " -"attribute ``attr`` is not restored in the unpickling environment::" -msgstr "" - -#: ../../library/pickle.rst:538 -msgid "" -"These restrictions are why picklable functions and classes must be defined " -"at the top level of a module." -msgstr "" - -#: ../../library/pickle.rst:541 -msgid "" -"Similarly, when class instances are pickled, their class's code and data are" -" not pickled along with them. Only the instance data are pickled. This is " -"done on purpose, so you can fix bugs in a class or add methods to the class " -"and still load objects that were created with an earlier version of the " -"class. If you plan to have long-lived objects that will see many versions " -"of a class, it may be worthwhile to put a version number in the objects so " -"that suitable conversions can be made by the class's " -":meth:`~object.__setstate__` method." -msgstr "" - -#: ../../library/pickle.rst:553 -msgid "Pickling Class Instances" -msgstr "" - -#: ../../library/pickle.rst:557 -msgid "" -"In this section, we describe the general mechanisms available to you to " -"define, customize, and control how class instances are pickled and " -"unpickled." -msgstr "" - -#: ../../library/pickle.rst:560 -msgid "" -"In most cases, no additional code is needed to make instances picklable. By" -" default, pickle will retrieve the class and the attributes of an instance " -"via introspection. When a class instance is unpickled, its " -":meth:`~object.__init__` method is usually *not* invoked. The default " -"behaviour first creates an uninitialized instance and then restores the " -"saved attributes. The following code shows an implementation of this " -"behaviour::" -msgstr "" - -#: ../../library/pickle.rst:575 -msgid "" -"Classes can alter the default behaviour by providing one or several special " -"methods:" -msgstr "" - -#: ../../library/pickle.rst:580 -msgid "" -"In protocols 2 and newer, classes that implements the " -":meth:`__getnewargs_ex__` method can dictate the values passed to the " -":meth:`__new__` method upon unpickling. The method must return a pair " -"``(args, kwargs)`` where *args* is a tuple of positional arguments and " -"*kwargs* a dictionary of named arguments for constructing the object. Those" -" will be passed to the :meth:`__new__` method upon unpickling." -msgstr "" - -#: ../../library/pickle.rst:588 -msgid "" -"You should implement this method if the :meth:`__new__` method of your class" -" requires keyword-only arguments. Otherwise, it is recommended for " -"compatibility to implement :meth:`__getnewargs__`." -msgstr "" - -#: ../../library/pickle.rst:592 -msgid ":meth:`__getnewargs_ex__` is now used in protocols 2 and 3." -msgstr "" - -#: ../../library/pickle.rst:598 -msgid "" -"This method serves a similar purpose as :meth:`__getnewargs_ex__`, but " -"supports only positional arguments. It must return a tuple of arguments " -"``args`` which will be passed to the :meth:`__new__` method upon unpickling." -msgstr "" - -#: ../../library/pickle.rst:602 -msgid "" -":meth:`__getnewargs__` will not be called if :meth:`__getnewargs_ex__` is " -"defined." -msgstr "" - -#: ../../library/pickle.rst:605 -msgid "" -"Before Python 3.6, :meth:`__getnewargs__` was called instead of " -":meth:`__getnewargs_ex__` in protocols 2 and 3." -msgstr "" - -#: ../../library/pickle.rst:612 -msgid "" -"Classes can further influence how their instances are pickled by overriding " -"the method :meth:`__getstate__`. It is called and the returned object is " -"pickled as the contents for the instance, instead of a default state. There " -"are several cases:" -msgstr "" - -#: ../../library/pickle.rst:617 -msgid "" -"For a class that has no instance :attr:`~object.__dict__` and no " -":attr:`~object.__slots__`, the default state is ``None``." -msgstr "" - -#: ../../library/pickle.rst:620 -msgid "" -"For a class that has an instance :attr:`~object.__dict__` and no " -":attr:`~object.__slots__`, the default state is ``self.__dict__``." -msgstr "" - -#: ../../library/pickle.rst:623 -msgid "" -"For a class that has an instance :attr:`~object.__dict__` and " -":attr:`~object.__slots__`, the default state is a tuple consisting of two " -"dictionaries: ``self.__dict__``, and a dictionary mapping slot names to " -"slot values. Only slots that have a value are included in the latter." -msgstr "" - -#: ../../library/pickle.rst:629 -msgid "" -"For a class that has :attr:`~object.__slots__` and no instance " -":attr:`~object.__dict__`, the default state is a tuple whose first item is " -"``None`` and whose second item is a dictionary mapping slot names to slot " -"values described in the previous bullet." -msgstr "" - -#: ../../library/pickle.rst:634 -msgid "" -"Added the default implementation of the ``__getstate__()`` method in the " -":class:`object` class." -msgstr "" - -#: ../../library/pickle.rst:641 -msgid "" -"Upon unpickling, if the class defines :meth:`__setstate__`, it is called " -"with the unpickled state. In that case, there is no requirement for the " -"state object to be a dictionary. Otherwise, the pickled state must be a " -"dictionary and its items are assigned to the new instance's dictionary." -msgstr "" - -#: ../../library/pickle.rst:648 -msgid "" -"If :meth:`__reduce__` returns a state with value ``None`` at pickling, the " -":meth:`__setstate__` method will not be called upon unpickling." -msgstr "" - -#: ../../library/pickle.rst:652 -msgid "" -"Refer to the section :ref:`pickle-state` for more information about how to " -"use the methods :meth:`~object.__getstate__` and " -":meth:`~object.__setstate__`." -msgstr "" - -#: ../../library/pickle.rst:657 -msgid "" -"At unpickling time, some methods like :meth:`~object.__getattr__`, " -":meth:`~object.__getattribute__`, or :meth:`~object.__setattr__` may be " -"called upon the instance. In case those methods rely on some internal " -"invariant being true, the type should implement :meth:`~object.__new__` to " -"establish such an invariant, as :meth:`~object.__init__` is not called when " -"unpickling an instance." -msgstr "" - -#: ../../library/pickle.rst:666 -msgid "" -"As we shall see, pickle does not use directly the methods described above. " -"In fact, these methods are part of the copy protocol which implements the " -":meth:`~object.__reduce__` special method. The copy protocol provides a " -"unified interface for retrieving the data necessary for pickling and copying" -" objects. [#]_" -msgstr "" - -#: ../../library/pickle.rst:672 -msgid "" -"Although powerful, implementing :meth:`~object.__reduce__` directly in your " -"classes is error prone. For this reason, class designers should use the " -"high-level interface (i.e., :meth:`~object.__getnewargs_ex__`, " -":meth:`~object.__getstate__` and :meth:`~object.__setstate__`) whenever " -"possible. We will show, however, cases where using :meth:`!__reduce__` is " -"the only option or leads to more efficient pickling or both." -msgstr "" - -#: ../../library/pickle.rst:681 -msgid "" -"The interface is currently defined as follows. The :meth:`__reduce__` " -"method takes no argument and shall return either a string or preferably a " -"tuple (the returned object is often referred to as the \"reduce value\")." -msgstr "" - -#: ../../library/pickle.rst:685 -msgid "" -"If a string is returned, the string should be interpreted as the name of a " -"global variable. It should be the object's local name relative to its " -"module; the pickle module searches the module namespace to determine the " -"object's module. This behaviour is typically useful for singletons." -msgstr "" - -#: ../../library/pickle.rst:690 -msgid "" -"When a tuple is returned, it must be between two and six items long. " -"Optional items can either be omitted, or ``None`` can be provided as their " -"value. The semantics of each item are in order:" -msgstr "" - -#: ../../library/pickle.rst:696 -msgid "" -"A callable object that will be called to create the initial version of the " -"object." -msgstr "" - -#: ../../library/pickle.rst:699 -msgid "" -"A tuple of arguments for the callable object. An empty tuple must be given " -"if the callable does not accept any argument." -msgstr "" - -#: ../../library/pickle.rst:702 -msgid "" -"Optionally, the object's state, which will be passed to the object's " -":meth:`__setstate__` method as previously described. If the object has no " -"such method then, the value must be a dictionary and it will be added to the" -" object's :attr:`~object.__dict__` attribute." -msgstr "" - -#: ../../library/pickle.rst:707 -msgid "" -"Optionally, an iterator (and not a sequence) yielding successive items. " -"These items will be appended to the object either using ``obj.append(item)``" -" or, in batch, using ``obj.extend(list_of_items)``. This is primarily used " -"for list subclasses, but may be used by other classes as long as they have " -":ref:`append and extend methods ` with the appropriate " -"signature. (Whether :meth:`!append` or :meth:`!extend` is used depends on " -"which pickle protocol version is used as well as the number of items to " -"append, so both must be supported.)" -msgstr "" - -#: ../../library/pickle.rst:717 -msgid "" -"Optionally, an iterator (not a sequence) yielding successive key-value " -"pairs. These items will be stored to the object using ``obj[key] = value``." -" This is primarily used for dictionary subclasses, but may be used by other" -" classes as long as they implement :meth:`__setitem__`." -msgstr "" - -#: ../../library/pickle.rst:722 -msgid "" -"Optionally, a callable with a ``(obj, state)`` signature. This callable " -"allows the user to programmatically control the state-updating behavior of a" -" specific object, instead of using ``obj``'s static :meth:`__setstate__` " -"method. If not ``None``, this callable will have priority over ``obj``'s " -":meth:`__setstate__`." -msgstr "" - -#: ../../library/pickle.rst:728 -msgid "The optional sixth tuple item, ``(obj, state)``, was added." -msgstr "" - -#: ../../library/pickle.rst:734 -msgid "" -"Alternatively, a :meth:`__reduce_ex__` method may be defined. The only " -"difference is this method should take a single integer argument, the " -"protocol version. When defined, pickle will prefer it over the " -":meth:`__reduce__` method. In addition, :meth:`__reduce__` automatically " -"becomes a synonym for the extended version. The main use for this method is" -" to provide backwards-compatible reduce values for older Python releases." -msgstr "" - -#: ../../library/pickle.rst:746 -msgid "Persistence of External Objects" -msgstr "" - -#: ../../library/pickle.rst:752 -msgid "" -"For the benefit of object persistence, the :mod:`pickle` module supports the" -" notion of a reference to an object outside the pickled data stream. Such " -"objects are referenced by a persistent ID, which should be either a string " -"of alphanumeric characters (for protocol 0) [#]_ or just an arbitrary object" -" (for any newer protocol)." -msgstr "" - -#: ../../library/pickle.rst:758 -msgid "" -"The resolution of such persistent IDs is not defined by the :mod:`pickle` " -"module; it will delegate this resolution to the user-defined methods on the " -"pickler and unpickler, :meth:`~Pickler.persistent_id` and " -":meth:`~Unpickler.persistent_load` respectively." -msgstr "" - -#: ../../library/pickle.rst:763 -msgid "" -"To pickle objects that have an external persistent ID, the pickler must have" -" a custom :meth:`~Pickler.persistent_id` method that takes an object as an " -"argument and returns either ``None`` or the persistent ID for that object. " -"When ``None`` is returned, the pickler simply pickles the object as normal. " -"When a persistent ID string is returned, the pickler will pickle that " -"object, along with a marker so that the unpickler will recognize it as a " -"persistent ID." -msgstr "" - -#: ../../library/pickle.rst:770 -msgid "" -"To unpickle external objects, the unpickler must have a custom " -":meth:`~Unpickler.persistent_load` method that takes a persistent ID object " -"and returns the referenced object." -msgstr "" - -#: ../../library/pickle.rst:774 -msgid "" -"Here is a comprehensive example presenting how persistent ID can be used to " -"pickle external objects by reference." -msgstr "" - -#: ../../library/pickle.rst:782 -msgid "Dispatch Tables" -msgstr "" - -#: ../../library/pickle.rst:784 -msgid "" -"If one wants to customize pickling of some classes without disturbing any " -"other code which depends on pickling, then one can create a pickler with a " -"private dispatch table." -msgstr "" - -#: ../../library/pickle.rst:788 -msgid "" -"The global dispatch table managed by the :mod:`copyreg` module is available " -"as :data:`!copyreg.dispatch_table`. Therefore, one may choose to use a " -"modified copy of :data:`!copyreg.dispatch_table` as a private dispatch " -"table." -msgstr "" - -#: ../../library/pickle.rst:793 -msgid "For example ::" -msgstr "舉例來說： ::" - -#: ../../library/pickle.rst:800 -msgid "" -"creates an instance of :class:`pickle.Pickler` with a private dispatch table" -" which handles the ``SomeClass`` class specially. Alternatively, the code " -"::" -msgstr "" - -#: ../../library/pickle.rst:810 -msgid "" -"does the same but all instances of ``MyPickler`` will by default share the " -"private dispatch table. On the other hand, the code ::" -msgstr "" - -#: ../../library/pickle.rst:817 -msgid "" -"modifies the global dispatch table shared by all users of the :mod:`copyreg`" -" module." -msgstr "" - -#: ../../library/pickle.rst:822 -msgid "Handling Stateful Objects" -msgstr "" - -#: ../../library/pickle.rst:828 -msgid "" -"Here's an example that shows how to modify pickling behavior for a class. " -"The :class:`!TextReader` class below opens a text file, and returns the line" -" number and line contents each time its :meth:`!readline` method is called. " -"If a :class:`!TextReader` instance is pickled, all attributes *except* the " -"file object member are saved. When the instance is unpickled, the file is " -"reopened, and reading resumes from the last location. The " -":meth:`!__setstate__` and :meth:`!__getstate__` methods are used to " -"implement this behavior. ::" -msgstr "" - -#: ../../library/pickle.rst:874 -msgid "A sample usage might be something like this::" -msgstr "" - -#: ../../library/pickle.rst:888 -msgid "Custom Reduction for Types, Functions, and Other Objects" -msgstr "" - -#: ../../library/pickle.rst:892 -msgid "" -"Sometimes, :attr:`~Pickler.dispatch_table` may not be flexible enough. In " -"particular we may want to customize pickling based on another criterion than" -" the object's type, or we may want to customize the pickling of functions " -"and classes." -msgstr "" - -#: ../../library/pickle.rst:897 -msgid "" -"For those cases, it is possible to subclass from the :class:`Pickler` class " -"and implement a :meth:`~Pickler.reducer_override` method. This method can " -"return an arbitrary reduction tuple (see :meth:`~object.__reduce__`). It can" -" alternatively return :data:`NotImplemented` to fallback to the traditional " -"behavior." -msgstr "" - -#: ../../library/pickle.rst:902 -msgid "" -"If both the :attr:`~Pickler.dispatch_table` and " -":meth:`~Pickler.reducer_override` are defined, then " -":meth:`~Pickler.reducer_override` method takes priority." -msgstr "" - -#: ../../library/pickle.rst:907 -msgid "" -"For performance reasons, :meth:`~Pickler.reducer_override` may not be called" -" for the following objects: ``None``, ``True``, ``False``, and exact " -"instances of :class:`int`, :class:`float`, :class:`bytes`, :class:`str`, " -":class:`dict`, :class:`set`, :class:`frozenset`, :class:`list` and " -":class:`tuple`." -msgstr "" - -#: ../../library/pickle.rst:913 -msgid "" -"Here is a simple example where we allow pickling and reconstructing a given " -"class::" -msgstr "" - -#: ../../library/pickle.rst:948 -msgid "Out-of-band Buffers" -msgstr "" - -#: ../../library/pickle.rst:952 -msgid "" -"In some contexts, the :mod:`pickle` module is used to transfer massive " -"amounts of data. Therefore, it can be important to minimize the number of " -"memory copies, to preserve performance and resource consumption. However, " -"normal operation of the :mod:`pickle` module, as it transforms a graph-like " -"structure of objects into a sequential stream of bytes, intrinsically " -"involves copying data to and from the pickle stream." -msgstr "" - -#: ../../library/pickle.rst:959 -msgid "" -"This constraint can be eschewed if both the *provider* (the implementation " -"of the object types to be transferred) and the *consumer* (the " -"implementation of the communications system) support the out-of-band " -"transfer facilities provided by pickle protocol 5 and higher." -msgstr "" - -#: ../../library/pickle.rst:965 -msgid "Provider API" -msgstr "" - -#: ../../library/pickle.rst:967 -msgid "" -"The large data objects to be pickled must implement a " -":meth:`~object.__reduce_ex__` method specialized for protocol 5 and higher, " -"which returns a :class:`PickleBuffer` instance (instead of e.g. a " -":class:`bytes` object) for any large data." -msgstr "" - -#: ../../library/pickle.rst:972 -msgid "" -"A :class:`PickleBuffer` object *signals* that the underlying buffer is " -"eligible for out-of-band data transfer. Those objects remain compatible " -"with normal usage of the :mod:`pickle` module. However, consumers can also " -"opt-in to tell :mod:`pickle` that they will handle those buffers by " -"themselves." -msgstr "" - -#: ../../library/pickle.rst:979 -msgid "Consumer API" -msgstr "" - -#: ../../library/pickle.rst:981 -msgid "" -"A communications system can enable custom handling of the " -":class:`PickleBuffer` objects generated when serializing an object graph." -msgstr "" - -#: ../../library/pickle.rst:984 -msgid "" -"On the sending side, it needs to pass a *buffer_callback* argument to " -":class:`Pickler` (or to the :func:`dump` or :func:`dumps` function), which " -"will be called with each :class:`PickleBuffer` generated while pickling the " -"object graph. Buffers accumulated by the *buffer_callback* will not see " -"their data copied into the pickle stream, only a cheap marker will be " -"inserted." -msgstr "" - -#: ../../library/pickle.rst:991 -msgid "" -"On the receiving side, it needs to pass a *buffers* argument to " -":class:`Unpickler` (or to the :func:`load` or :func:`loads` function), which" -" is an iterable of the buffers which were passed to *buffer_callback*. That " -"iterable should produce buffers in the same order as they were passed to " -"*buffer_callback*. Those buffers will provide the data expected by the " -"reconstructors of the objects whose pickling produced the original " -":class:`PickleBuffer` objects." -msgstr "" - -#: ../../library/pickle.rst:999 -msgid "" -"Between the sending side and the receiving side, the communications system " -"is free to implement its own transfer mechanism for out-of-band buffers. " -"Potential optimizations include the use of shared memory or datatype-" -"dependent compression." -msgstr "" - -#: ../../library/pickle.rst:1005 -msgid "Example" -msgstr "範例" - -#: ../../library/pickle.rst:1007 -msgid "" -"Here is a trivial example where we implement a :class:`bytearray` subclass " -"able to participate in out-of-band buffer pickling::" -msgstr "" - -#: ../../library/pickle.rst:1031 -msgid "" -"The reconstructor (the ``_reconstruct`` class method) returns the buffer's " -"providing object if it has the right type. This is an easy way to simulate " -"zero-copy behaviour on this toy example." -msgstr "" - -#: ../../library/pickle.rst:1035 -msgid "" -"On the consumer side, we can pickle those objects the usual way, which when " -"unserialized will give us a copy of the original object::" -msgstr "" - -#: ../../library/pickle.rst:1044 -msgid "" -"But if we pass a *buffer_callback* and then give back the accumulated " -"buffers when unserializing, we are able to get back the original object::" -msgstr "" - -#: ../../library/pickle.rst:1054 -msgid "" -"This example is limited by the fact that :class:`bytearray` allocates its " -"own memory: you cannot create a :class:`bytearray` instance that is backed " -"by another object's memory. However, third-party datatypes such as NumPy " -"arrays do not have this limitation, and allow use of zero-copy pickling (or " -"making as few copies as possible) when transferring between distinct " -"processes or systems." -msgstr "" - -#: ../../library/pickle.rst:1061 -msgid ":pep:`574` -- Pickle protocol 5 with out-of-band data" -msgstr "" - -#: ../../library/pickle.rst:1067 -msgid "Restricting Globals" -msgstr "" - -#: ../../library/pickle.rst:1072 -msgid "" -"By default, unpickling will import any class or function that it finds in " -"the pickle data. For many applications, this behaviour is unacceptable as " -"it permits the unpickler to import and invoke arbitrary code. Just consider" -" what this hand-crafted pickle data stream does when loaded::" -msgstr "" - -#: ../../library/pickle.rst:1082 -msgid "" -"In this example, the unpickler imports the :func:`os.system` function and " -"then apply the string argument \"echo hello world\". Although this example " -"is inoffensive, it is not difficult to imagine one that could damage your " -"system." -msgstr "" - -#: ../../library/pickle.rst:1086 -msgid "" -"For this reason, you may want to control what gets unpickled by customizing " -":meth:`Unpickler.find_class`. Unlike its name suggests, " -":meth:`Unpickler.find_class` is called whenever a global (i.e., a class or a" -" function) is requested. Thus it is possible to either completely forbid " -"globals or restrict them to a safe subset." -msgstr "" - -#: ../../library/pickle.rst:1092 -msgid "" -"Here is an example of an unpickler allowing only few safe classes from the " -":mod:`builtins` module to be loaded::" -msgstr "" - -#: ../../library/pickle.rst:1121 -msgid "A sample usage of our unpickler working as intended::" -msgstr "" - -#: ../../library/pickle.rst:1140 -msgid "" -"As our examples shows, you have to be careful with what you allow to be " -"unpickled. Therefore if security is a concern, you may want to consider " -"alternatives such as the marshalling API in :mod:`xmlrpc.client` or third-" -"party solutions." -msgstr "" - -#: ../../library/pickle.rst:1147 -msgid "Performance" -msgstr "" - -#: ../../library/pickle.rst:1149 -msgid "" -"Recent versions of the pickle protocol (from protocol 2 and upwards) feature" -" efficient binary encodings for several common features and built-in types. " -"Also, the :mod:`pickle` module has a transparent optimizer written in C." -msgstr "" - -#: ../../library/pickle.rst:1157 -msgid "Examples" -msgstr "範例" - -#: ../../library/pickle.rst:1159 -msgid "" -"For the simplest code, use the :func:`dump` and :func:`load` functions. ::" -msgstr "" - -#: ../../library/pickle.rst:1175 -msgid "The following example reads the resulting pickled data. ::" -msgstr "" - -#: ../../library/pickle.rst:1191 -msgid "Module :mod:`copyreg`" -msgstr ":mod:`copyreg` 模組" - -#: ../../library/pickle.rst:1192 -msgid "Pickle interface constructor registration for extension types." -msgstr "" - -#: ../../library/pickle.rst:1194 -msgid "Module :mod:`pickletools`" -msgstr ":mod:`pickletools` 模組" - -#: ../../library/pickle.rst:1195 -msgid "Tools for working with and analyzing pickled data." -msgstr "" - -#: ../../library/pickle.rst:1197 -msgid "Module :mod:`shelve`" -msgstr ":mod:`shelve` 模組" - -#: ../../library/pickle.rst:1198 -msgid "Indexed databases of objects; uses :mod:`pickle`." -msgstr "" - -#: ../../library/pickle.rst:1200 -msgid "Module :mod:`copy`" -msgstr ":mod:`copy` 模組" - -#: ../../library/pickle.rst:1201 -msgid "Shallow and deep object copying." -msgstr "" - -#: ../../library/pickle.rst:1203 -msgid "Module :mod:`marshal`" -msgstr ":mod:`marshal` 模組" - -#: ../../library/pickle.rst:1204 -msgid "High-performance serialization of built-in types." -msgstr "" - -#: ../../library/pickle.rst:1208 -msgid "Footnotes" -msgstr "註解" - -#: ../../library/pickle.rst:1209 -msgid "Don't confuse this with the :mod:`marshal` module" -msgstr "" - -#: ../../library/pickle.rst:1211 -msgid "" -"This is why :keyword:`lambda` functions cannot be pickled: all " -":keyword:`!lambda` functions share the same name: ````." -msgstr "" - -#: ../../library/pickle.rst:1214 -msgid "" -"The exception raised will likely be an :exc:`ImportError` or an " -":exc:`AttributeError` but it could be something else." -msgstr "" - -#: ../../library/pickle.rst:1217 -msgid "" -"The :mod:`copy` module uses this protocol for shallow and deep copying " -"operations." -msgstr "" - -#: ../../library/pickle.rst:1220 -msgid "" -"The limitation on alphanumeric characters is due to the fact that persistent" -" IDs in protocol 0 are delimited by the newline character. Therefore if any" -" kind of newline characters occurs in persistent IDs, the resulting pickled " -"data will become unreadable." -msgstr "" - -#: ../../library/pickle.rst:12 -msgid "persistence" -msgstr "persistence（持續性）" - -#: ../../library/pickle.rst:12 -msgid "persistent" -msgstr "persistent（持續）" - -#: ../../library/pickle.rst:12 -msgid "objects" -msgstr "objects（物件）" - -#: ../../library/pickle.rst:12 -msgid "serializing" -msgstr "serializing（序列化）" - -#: ../../library/pickle.rst:12 -msgid "marshalling" -msgstr "marshalling" - -#: ../../library/pickle.rst:12 -msgid "flattening" -msgstr "flattening（攤平）" - -#: ../../library/pickle.rst:12 -msgid "pickling" -msgstr "pickling" - -#: ../../library/pickle.rst:123 -msgid "External Data Representation" -msgstr "External Data Representation（外部資料表示法）" - -#: ../../library/pickle.rst:664 -msgid "copy" -msgstr "copy（複製）" - -#: ../../library/pickle.rst:664 -msgid "protocol" -msgstr "protocol（協定）" - -#: ../../library/pickle.rst:748 -msgid "persistent_id (pickle protocol)" -msgstr "persistent_id（pickle 協定）" - -#: ../../library/pickle.rst:748 -msgid "persistent_load (pickle protocol)" -msgstr "persistent_load（pickle 協定）" - -#: ../../library/pickle.rst:824 -msgid "__getstate__() (copy protocol)" -msgstr "__getstate__()（copy 協定）" - -#: ../../library/pickle.rst:824 -msgid "__setstate__() (copy protocol)" -msgstr "__setstate__()（copy 協定）" - -#: ../../library/pickle.rst:1069 -msgid "find_class() (pickle protocol)" -msgstr "find_class()（pickle 協定）" +# Copyright (C) 2001-2024, Python Software Foundation +# This file is distributed under the same license as the Python package. +# +# Translators: +# Skylull, 2024 +msgid "" +msgstr "" +"Project-Id-Version: Python 3.12\n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2024-05-09 00:03+0000\n" +"PO-Revision-Date: 2018-05-23 16:07+0000\n" +"Last-Translator: Adrian Liaw \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" +"Plural-Forms: nplurals=1; plural=0;\n" + +#: ../../library/pickle.rst:2 +msgid ":mod:`!pickle` --- Python object serialization" +msgstr ":mod:`!pickle` --- Python 物件序列化" + +#: ../../library/pickle.rst:10 +msgid "**Source code:** :source:`Lib/pickle.py`" +msgstr "**原始碼：**\\ :source:`Lib/pickle.py`" + +# Skylull: 我對 `pickle` 的命名原因進行了簡單的搜尋，只找到一則討論 +# https://stackoverflow.com/questions/27324986/pickles-why-are-they-called- +# that +# 其中表示這名字很可能只是為了隨便找一個p開頭的單字、或原始開發人員的內部玩笑造成的約定俗成。也有人表示醃製黃瓜（pickle- +# ing）的目標就是保存和存放，所以取了這個名字。 +# 無論如何似乎沒有一個定論。 +# 因為不確定是否與醃漬的這個梗有關，我暫時選擇使用 `封裝` 與 `拆封` 作為譯文，大致保存那個把東西處裡後裝起來的感覺但又不至於太奇怪。 +# 唯一需要擔心的是是否有與 `encapsulation` （封裝，網路協定名詞）或 `package`（封包，網路協定名詞）搞混的可能。 +#: ../../library/pickle.rst:22 +msgid "" +"The :mod:`pickle` module implements binary protocols for serializing and de-" +"serializing a Python object structure. *\"Pickling\"* is the process " +"whereby a Python object hierarchy is converted into a byte stream, and " +"*\"unpickling\"* is the inverse operation, whereby a byte stream (from a :" +"term:`binary file` or :term:`bytes-like object`) is converted back into an " +"object hierarchy. Pickling (and unpickling) is alternatively known as " +"\"serialization\", \"marshalling,\" [#]_ or \"flattening\"; however, to " +"avoid confusion, the terms used here are \"pickling\" and \"unpickling\"." +msgstr "" +":mod:`pickle` 模組實作的是一個在二進位層級上對 Python 物件進行序列化" +"（serialize）或去序列化（de-serialize）。*\"Pickling\"* 用於專門指摘將一個 " +"Python 物件轉換為一個二進位串流的過程，*\"unpickling\"* 則相反，指的是將一個" +"（來自 :term:`binary file` 或 :term:`bytes-like object` 的）二進位串流轉換回 " +"Python 物件的過程。Pickling（和 unpickling）的過程也可能被稱作 " +"\"serialization\", \"marshalling,\" [#]_ 或 \"flattening\"。不過，為了避免混" +"淆，本文件將統一稱作封裝（pickling）、拆封（unpickling）。" + +#: ../../library/pickle.rst:33 +msgid "The ``pickle`` module **is not secure**. Only unpickle data you trust." +msgstr "``pickle`` 模組**並不安全**，切記只拆封你信任的資料。" + +#: ../../library/pickle.rst:35 +msgid "" +"It is possible to construct malicious pickle data which will **execute " +"arbitrary code during unpickling**. Never unpickle data that could have come " +"from an untrusted source, or that could have been tampered with." +msgstr "" +"pickle 封包是有可能被建立來在拆封的時候**執行任意惡意程式碼**的。絕對不要拆封" +"任何你無法信任其來源、或可能被修改過的 pickle 封包。" + +#: ../../library/pickle.rst:39 +msgid "" +"Consider signing data with :mod:`hmac` if you need to ensure that it has not " +"been tampered with." +msgstr "建議你可以使用 :mod:`hmac` 模組來簽署這個封包，以確保其未被修改過。" + +#: ../../library/pickle.rst:42 +msgid "" +"Safer serialization formats such as :mod:`json` may be more appropriate if " +"you are processing untrusted data. See :ref:`comparison-with-json`." +msgstr "" +"如果你在處理不受信任的資料，其他比較安全的序列化格式（例如 :mod:`json`）可能" +"會更適合。請參照 See :ref:`comparison-with-json` 的說明。" + +#: ../../library/pickle.rst:47 +msgid "Relationship to other Python modules" +msgstr "和其他 Python 模組的關係" + +#: ../../library/pickle.rst:50 +msgid "Comparison with ``marshal``" +msgstr "和 ``marshal`` 的比較" + +#: ../../library/pickle.rst:52 +msgid "" +"Python has a more primitive serialization module called :mod:`marshal`, but " +"in general :mod:`pickle` should always be the preferred way to serialize " +"Python objects. :mod:`marshal` exists primarily to support Python's :file:`." +"pyc` files." +msgstr "" +"Python 有另一個比較原始的序列化模組叫 :mod:`marshal`，不過其設計目的是為了支" +"援 Python 的預編譯功能 :file:`.pyc` 運作。總地來說，沒事不要用 :mod:" +"`marshal`。" + +#: ../../library/pickle.rst:57 +msgid "" +"The :mod:`pickle` module differs from :mod:`marshal` in several significant " +"ways:" +msgstr ":mod:`pickle` 和 :mod:`marshal` 有幾個明顯不同的地方：" + +#: ../../library/pickle.rst:59 +msgid "" +"The :mod:`pickle` module keeps track of the objects it has already " +"serialized, so that later references to the same object won't be serialized " +"again. :mod:`marshal` doesn't do this." +msgstr "" +":mod:`pickle` 會記住哪些物件已經被序列化過了，稍後再次參照到這個物件的時候才" +"不會進行重複的序列化。:mod:`marshal` 沒有這個功能。" + +#: ../../library/pickle.rst:63 +msgid "" +"This has implications both for recursive objects and object sharing. " +"Recursive objects are objects that contain references to themselves. These " +"are not handled by marshal, and in fact, attempting to marshal recursive " +"objects will crash your Python interpreter. Object sharing happens when " +"there are multiple references to the same object in different places in the " +"object hierarchy being serialized. :mod:`pickle` stores such objects only " +"once, and ensures that all other references point to the master copy. " +"Shared objects remain shared, which can be very important for mutable " +"objects." +msgstr "" +"這對遞迴物件和物件共用都有影響。遞迴物件是指包含自我參照的物件。這些情況在 " +"marshal 模組中不會被處理，若嘗試使用 marshal 處理遞迴物件會導致 Python 直譯器" +"崩潰。物件共用發生在序列化的物件階層中，不同位置對同一物件有多個參照時。:mod:" +"`pickle` 只會儲存這個被參照的物件一次，並確保所有其他參照指向這個主要的版本。" +"共用的物件會保持共用，這對於可變（mutable）物件來說非常重要。" + +#: ../../library/pickle.rst:72 +msgid "" +":mod:`marshal` cannot be used to serialize user-defined classes and their " +"instances. :mod:`pickle` can save and restore class instances " +"transparently, however the class definition must be importable and live in " +"the same module as when the object was stored." +msgstr "" +":mod:`marshal` 無法序列化使用者自訂的類別和的實例。:mod:`pickle` 則可以讓使用" +"者儲存並還原自訂的類別實例，前提是儲存時該類別的定義存在於與要被儲存的物件所" +"在的模組中、且可以被引入（import）。" + +#: ../../library/pickle.rst:77 +msgid "" +"The :mod:`marshal` serialization format is not guaranteed to be portable " +"across Python versions. Because its primary job in life is to support :file:" +"`.pyc` files, the Python implementers reserve the right to change the " +"serialization format in non-backwards compatible ways should the need arise. " +"The :mod:`pickle` serialization format is guaranteed to be backwards " +"compatible across Python releases provided a compatible pickle protocol is " +"chosen and pickling and unpickling code deals with Python 2 to Python 3 type " +"differences if your data is crossing that unique breaking change language " +"boundary." +msgstr "" +":mod:`marshal` 序列化格式無法保證能在不同版本的 Python 之間移植。因為其主要的" +"作用是支援 :file:`.pyc` 檔案的運作，Python 的實作人員會在需要時實作無法前向相" +"容的序列化方式。但只要選擇了相容的 pickle 協定，且處理了 Python 2 和 Python " +"3 之間的資料類型差異，:mod:`pickle` 序列化協定能保證在不同 Python 版本間的相" +"容性。" + +#: ../../library/pickle.rst:90 +msgid "Comparison with ``json``" +msgstr "和 ``json`` 的比較" + +#: ../../library/pickle.rst:92 +msgid "" +"There are fundamental differences between the pickle protocols and `JSON " +"(JavaScript Object Notation) `_:" +msgstr "" +"pickle 協定和 `JSON (JavaScript Object Notation) `_ 有一些" +"根本上的不同：" + +#: ../../library/pickle.rst:95 +msgid "" +"JSON is a text serialization format (it outputs unicode text, although most " +"of the time it is then encoded to ``utf-8``), while pickle is a binary " +"serialization format;" +msgstr "" +"JSON 以文字形式作為序列化的輸出（輸出 unicode 文字，但大多數又會被編碼為 " +"``UTF-8``），而 pickle 則是以二進位形式作為序列化的輸出；" + +#: ../../library/pickle.rst:99 +msgid "JSON is human-readable, while pickle is not;" +msgstr "JSON 是人類可讀的，而 pickle 則無法；" + +#: ../../library/pickle.rst:101 +msgid "" +"JSON is interoperable and widely used outside of the Python ecosystem, while " +"pickle is Python-specific;" +msgstr "" +"JSON 具有高互通性（interoperability）且在 Python 以外的環境也被大量利用，但 " +"pickle 只能在 Python 內使用。" + +# Skylull: introspection, introspection facilities +# https://zh.wikipedia.org/wiki/%E5%86%85%E7%9C%81_(%E8%AE%A1%E7%AE%97%E6%9C%BA%E7%A7%91%E5%AD%A6) +# https://book.pythontips.com/en/latest/object_introspection.html +# https://www.geeksforgeeks.org/code-introspection-in-python/ +#: ../../library/pickle.rst:104 +msgid "" +"JSON, by default, can only represent a subset of the Python built-in types, " +"and no custom classes; pickle can represent an extremely large number of " +"Python types (many of them automatically, by clever usage of Python's " +"introspection facilities; complex cases can be tackled by implementing :ref:" +"`specific object APIs `);" +msgstr "" +"預設狀態下的 JSON 只能紀錄一小部份的 Python 內建型別，且無法紀錄自訂類別；但" +"透過 Python 的自省功能，pickle 可以紀錄絕大多數的 Python 型別（其他比較複雜的" +"狀況也可以透過實作 :ref:`specific object APIs ` 來解決）；" + +#: ../../library/pickle.rst:110 +msgid "" +"Unlike pickle, deserializing untrusted JSON does not in itself create an " +"arbitrary code execution vulnerability." +msgstr "" +"去序列化不安全的 JSON 不會產生任意程式執行的風險，但去序列化不安全的 pickle " +"會。" + +#: ../../library/pickle.rst:114 +msgid "" +"The :mod:`json` module: a standard library module allowing JSON " +"serialization and deserialization." +msgstr "" +":mod:`json` module: 是標準函式庫的一部分，可讓使用者進行 JSON 的序列化與去序" +"列化。" + +#: ../../library/pickle.rst:121 +msgid "Data stream format" +msgstr "資料串流格式" + +#: ../../library/pickle.rst:126 +msgid "" +"The data format used by :mod:`pickle` is Python-specific. This has the " +"advantage that there are no restrictions imposed by external standards such " +"as JSON or XDR (which can't represent pointer sharing); however it means " +"that non-Python programs may not be able to reconstruct pickled Python " +"objects." +msgstr "" +":mod:`pickle` 使用的資料格式是針對 Python 而設計的。好處是他不會受到外部標準" +"（像是 JSON 或 XDR，而 XDR 無法紀錄指標共用）的限制；不過這也代表其他不是 " +"Python 的程式可能無法重建 pickle 封裝的 Python 物件。" + +#: ../../library/pickle.rst:131 +msgid "" +"By default, the :mod:`pickle` data format uses a relatively compact binary " +"representation. If you need optimal size characteristics, you can " +"efficiently :doc:`compress ` pickled data." +msgstr "" +"以預設設定來說，:mod:`pickle` 使用相對緊湊的二進位形式來儲存資料。如果你需要" +"盡可能地縮小檔案大小，你可以\\\\ :doc:`壓縮 `\\\\ 封裝的資料。" + +#: ../../library/pickle.rst:135 +msgid "" +"The module :mod:`pickletools` contains tools for analyzing data streams " +"generated by :mod:`pickle`. :mod:`pickletools` source code has extensive " +"comments about opcodes used by pickle protocols." +msgstr "" +":mod:`pickletools` 含有工具可分析 :mod:`pickle` 所產生的資料流。:mod:" +"`pickletools` 的源始碼詳細地記載了所有 pickle 協定的操作碼（opcode）。" + +#: ../../library/pickle.rst:139 +msgid "" +"There are currently 6 different protocols which can be used for pickling. " +"The higher the protocol used, the more recent the version of Python needed " +"to read the pickle produced." +msgstr "" +"截至目前為止，共有六種不同版本的協定可用於封裝 pickle。數字越大版本代表你需" +"要使用越新的 Python 版本來拆封相應的 pickle 封裝。" + +#: ../../library/pickle.rst:143 +msgid "" +"Protocol version 0 is the original \"human-readable\" protocol and is " +"backwards compatible with earlier versions of Python." +msgstr "" +"版本 0 的協定是最初「人類可讀」的版本，且可以向前支援早期版本的 Python。" + +#: ../../library/pickle.rst:146 +msgid "" +"Protocol version 1 is an old binary format which is also compatible with " +"earlier versions of Python." +msgstr "版本 1 的協定使用舊的二進位格式，一樣能向前支援早期版本的 Python。" + +#: ../../library/pickle.rst:149 +msgid "" +"Protocol version 2 was introduced in Python 2.3. It provides much more " +"efficient pickling of :term:`new-style classes `. Refer " +"to :pep:`307` for information about improvements brought by protocol 2." +msgstr "" +"版本 2 的協定在 Python 2.3 中初次被引入。其可提供更高效率的 :term:`new-style " +"classes ` 封裝過程。請參閱 :pep:`307` 以了解版本 2 帶來的改" +"進。" + +#: ../../library/pickle.rst:153 +msgid "" +"Protocol version 3 was added in Python 3.0. It has explicit support for :" +"class:`bytes` objects and cannot be unpickled by Python 2.x. This was the " +"default protocol in Python 3.0--3.7." +msgstr "" +"版本 3 的協定在 Python 3.0 被新增。現在能支援封裝 :class:`bytes` 的物件且無法" +"被 2.x 版本的 Python 拆封。在 3.0～3.7 的 Python 預設使用 3 版協定。" + +#: ../../library/pickle.rst:157 +msgid "" +"Protocol version 4 was added in Python 3.4. It adds support for very large " +"objects, pickling more kinds of objects, and some data format " +"optimizations. It is the default protocol starting with Python 3.8. Refer " +"to :pep:`3154` for information about improvements brought by protocol 4." +msgstr "" +"版本 4 的協定在 Python 3.4 被新增。現在能支援超大物件的封裝、更多種型別的物件" +"以及針對部份資料格式的儲存進行最佳化。從 Python 3.8 起，預設使用第 4 版協定。" +"請參閱 :pep:`3154` 以了解第 4 版協定改進的細節。" + +#: ../../library/pickle.rst:163 +msgid "" +"Protocol version 5 was added in Python 3.8. It adds support for out-of-band " +"data and speedup for in-band data. Refer to :pep:`574` for information " +"about improvements brought by protocol 5." +msgstr "" +"版本 5 的協定在 Python 3.8 被新增。現在能支援帶外資料（Out-of-band data）並加" +"速帶內資料的處理速度。請參閱 :pep:`574` 以了解第 5 版協定改進的細節。" + +#: ../../library/pickle.rst:168 +msgid "" +"Serialization is a more primitive notion than persistence; although :mod:" +"`pickle` reads and writes file objects, it does not handle the issue of " +"naming persistent objects, nor the (even more complicated) issue of " +"concurrent access to persistent objects. The :mod:`pickle` module can " +"transform a complex object into a byte stream and it can transform the byte " +"stream into an object with the same internal structure. Perhaps the most " +"obvious thing to do with these byte streams is to write them onto a file, " +"but it is also conceivable to send them across a network or store them in a " +"database. The :mod:`shelve` module provides a simple interface to pickle " +"and unpickle objects on DBM-style database files." +msgstr "" +"資料序列化是一個比資料持久化更早出現的概念；雖然 :mod:`pickle` 可以讀寫檔案物" +"件，但它並不處理命名持久物件的問題，也不處理對持久物件的並行存取、一個更棘手" +"的問題。:mod:`pickle` 模組可以將複雜物件轉換成位元組串流，也可以將位元組串流" +"轉換回具有相同原始內部結構的物件。對這些位元組串流最常見的處理方式是將它們寫" +"入檔案中，但也可以將它們透過網路傳送或儲存在一個資料庫中。:mod:`shelve` 模組" +"提供了一個簡單的介面來讓使用者在 DBM 風格的資料庫檔案中對物件進行封裝和拆封的" +"操作。" + +#: ../../library/pickle.rst:181 +msgid "Module Interface" +msgstr "模組介面" + +#: ../../library/pickle.rst:183 +msgid "" +"To serialize an object hierarchy, you simply call the :func:`dumps` " +"function. Similarly, to de-serialize a data stream, you call the :func:" +"`loads` function. However, if you want more control over serialization and " +"de-serialization, you can create a :class:`Pickler` or an :class:`Unpickler` " +"object, respectively." +msgstr "" +"想要序列化一個物件，你只需要呼叫 :func:`dumps` 函數。而當你想要去序列化一個資" +"料流時，你只需要呼叫 :func:`loads` 即可。不過，若你希望能各自對序列化和去序列" +"化的過程中有更多的掌控度，你可以自訂一個 :class:`Pickler` 或 :class:" +"`Unpickler` 物件。" + +#: ../../library/pickle.rst:188 +msgid "The :mod:`pickle` module provides the following constants:" +msgstr ":mod:`pickle` 模組提供以下常數：" + +#: ../../library/pickle.rst:193 +msgid "" +"An integer, the highest :ref:`protocol version ` " +"available. This value can be passed as a *protocol* value to functions :" +"func:`dump` and :func:`dumps` as well as the :class:`Pickler` constructor." +msgstr "" +"一個整數，表示可使用的最高\\ :ref:`協定版本 `。這個值可作" +"為 *protocol* 的數值傳給 :func:`dump` 和 :func:`dumps` 函數以及 :class:" +"`Pickler` 建構式。" + +#: ../../library/pickle.rst:200 +msgid "" +"An integer, the default :ref:`protocol version ` used for " +"pickling. May be less than :data:`HIGHEST_PROTOCOL`. Currently the default " +"protocol is 4, first introduced in Python 3.4 and incompatible with previous " +"versions." +msgstr "" +"一個整數，指示用於序列化的預設\\ :ref:`協定版本 `。有可能小" +"於 :data:`HIGHEST_PROTOCOL`。目前的預設協定版本為 4，是在 Python 3.4 中首次引" +"入的，且與先前版本不相容。" + +#: ../../library/pickle.rst:207 +msgid "The default protocol is 3." +msgstr "預設協定版本為 3。" + +#: ../../library/pickle.rst:211 +msgid "The default protocol is 4." +msgstr "預設協定版本為 4。" + +#: ../../library/pickle.rst:213 +msgid "" +"The :mod:`pickle` module provides the following functions to make the " +"pickling process more convenient:" +msgstr ":mod:`pickle` 模組提供下列函數來簡化封裝的過程：" + +#: ../../library/pickle.rst:218 +msgid "" +"Write the pickled representation of the object *obj* to the open :term:`file " +"object` *file*. This is equivalent to ``Pickler(file, protocol).dump(obj)``." +msgstr "" +"將被封裝成 pickle 形式的 *obj* 寫入到已開啟的\\\\ term:`檔案物件 ` *file*。這等效於\\\\ ``Pickler(file, protocol).dump(obj)``。" + +#: ../../library/pickle.rst:222 +msgid "" +"Arguments *file*, *protocol*, *fix_imports* and *buffer_callback* have the " +"same meaning as in the :class:`Pickler` constructor." +msgstr "" +"引數 *file*、*protocol*、*fix_imports* 和 *buffer_callback* 的意義與 :class:" +"`Pickler` 建構式中的相同。" + +#: ../../library/pickle.rst:225 ../../library/pickle.rst:236 +#: ../../library/pickle.rst:328 +msgid "The *buffer_callback* argument was added." +msgstr "新增 *buffer_callback* 引數。" + +#: ../../library/pickle.rst:230 +msgid "" +"Return the pickled representation of the object *obj* as a :class:`bytes` " +"object, instead of writing it to a file." +msgstr "" +"將被封裝為 pickle 形式的 *obj* 以 :class:`bytes` 類別回傳，而非寫入進檔案。" + +#: ../../library/pickle.rst:233 +msgid "" +"Arguments *protocol*, *fix_imports* and *buffer_callback* have the same " +"meaning as in the :class:`Pickler` constructor." +msgstr "" +"引數 *protocol*、*fix_imports* 和 *buffer_callback* 的意義和 :class:" +"`Pickler` 建構式中的相同。" + +#: ../../library/pickle.rst:241 +msgid "" +"Read the pickled representation of an object from the open :term:`file " +"object` *file* and return the reconstituted object hierarchy specified " +"therein. This is equivalent to ``Unpickler(file).load()``." +msgstr "" +"從已開啟的 :term:`檔案物件 ` *file* 中讀取已序列化的物件，並傳回" +"其重建後的物件階層。這相當於呼叫 ``Unpickler(file).load()``。" + +#: ../../library/pickle.rst:245 ../../library/pickle.rst:260 +msgid "" +"The protocol version of the pickle is detected automatically, so no protocol " +"argument is needed. Bytes past the pickled representation of the object are " +"ignored." +msgstr "" +"模組會自動偵測 pickle 封包所使用的協定版本，所以無須另外指定。超出 pickle 封" +"包表示範圍的位元組將被忽略。" + +#: ../../library/pickle.rst:249 +msgid "" +"Arguments *file*, *fix_imports*, *encoding*, *errors*, *strict* and " +"*buffers* have the same meaning as in the :class:`Unpickler` constructor." +msgstr "" +"引數 *file*、*fix_imports*、*encoding*、*errors*、*strict* 和 *buffers* 的意" +"義和 :class:`Unpickler` 建構式中的相同。" + +#: ../../library/pickle.rst:252 ../../library/pickle.rst:267 +#: ../../library/pickle.rst:429 +msgid "The *buffers* argument was added." +msgstr "新增 *buffer* 引數。" + +#: ../../library/pickle.rst:257 +msgid "" +"Return the reconstituted object hierarchy of the pickled representation " +"*data* of an object. *data* must be a :term:`bytes-like object`." +msgstr "" + +#: ../../library/pickle.rst:264 +msgid "" +"Arguments *fix_imports*, *encoding*, *errors*, *strict* and *buffers* have " +"the same meaning as in the :class:`Unpickler` constructor." +msgstr "" + +#: ../../library/pickle.rst:271 +msgid "The :mod:`pickle` module defines three exceptions:" +msgstr "" + +#: ../../library/pickle.rst:275 +msgid "" +"Common base class for the other pickling exceptions. It inherits from :exc:" +"`Exception`." +msgstr "" + +#: ../../library/pickle.rst:280 +msgid "" +"Error raised when an unpicklable object is encountered by :class:`Pickler`. " +"It inherits from :exc:`PickleError`." +msgstr "" + +#: ../../library/pickle.rst:283 +msgid "" +"Refer to :ref:`pickle-picklable` to learn what kinds of objects can be " +"pickled." +msgstr "" + +#: ../../library/pickle.rst:288 +msgid "" +"Error raised when there is a problem unpickling an object, such as a data " +"corruption or a security violation. It inherits from :exc:`PickleError`." +msgstr "" + +#: ../../library/pickle.rst:291 +msgid "" +"Note that other exceptions may also be raised during unpickling, including " +"(but not necessarily limited to) AttributeError, EOFError, ImportError, and " +"IndexError." +msgstr "" + +#: ../../library/pickle.rst:296 +msgid "" +"The :mod:`pickle` module exports three classes, :class:`Pickler`, :class:" +"`Unpickler` and :class:`PickleBuffer`:" +msgstr "" + +#: ../../library/pickle.rst:301 +msgid "This takes a binary file for writing a pickle data stream." +msgstr "" + +#: ../../library/pickle.rst:303 +msgid "" +"The optional *protocol* argument, an integer, tells the pickler to use the " +"given protocol; supported protocols are 0 to :data:`HIGHEST_PROTOCOL`. If " +"not specified, the default is :data:`DEFAULT_PROTOCOL`. If a negative " +"number is specified, :data:`HIGHEST_PROTOCOL` is selected." +msgstr "" + +#: ../../library/pickle.rst:308 +msgid "" +"The *file* argument must have a write() method that accepts a single bytes " +"argument. It can thus be an on-disk file opened for binary writing, an :" +"class:`io.BytesIO` instance, or any other custom object that meets this " +"interface." +msgstr "" + +#: ../../library/pickle.rst:313 +msgid "" +"If *fix_imports* is true and *protocol* is less than 3, pickle will try to " +"map the new Python 3 names to the old module names used in Python 2, so that " +"the pickle data stream is readable with Python 2." +msgstr "" + +#: ../../library/pickle.rst:317 +msgid "" +"If *buffer_callback* is ``None`` (the default), buffer views are serialized " +"into *file* as part of the pickle stream." +msgstr "" + +#: ../../library/pickle.rst:320 +msgid "" +"If *buffer_callback* is not ``None``, then it can be called any number of " +"times with a buffer view. If the callback returns a false value (such as " +"``None``), the given buffer is :ref:`out-of-band `; otherwise " +"the buffer is serialized in-band, i.e. inside the pickle stream." +msgstr "" + +#: ../../library/pickle.rst:325 +msgid "" +"It is an error if *buffer_callback* is not ``None`` and *protocol* is " +"``None`` or smaller than 5." +msgstr "" + +#: ../../library/pickle.rst:333 +msgid "" +"Write the pickled representation of *obj* to the open file object given in " +"the constructor." +msgstr "" + +#: ../../library/pickle.rst:338 +msgid "Do nothing by default. This exists so a subclass can override it." +msgstr "" + +#: ../../library/pickle.rst:340 +msgid "" +"If :meth:`persistent_id` returns ``None``, *obj* is pickled as usual. Any " +"other value causes :class:`Pickler` to emit the returned value as a " +"persistent ID for *obj*. The meaning of this persistent ID should be " +"defined by :meth:`Unpickler.persistent_load`. Note that the value returned " +"by :meth:`persistent_id` cannot itself have a persistent ID." +msgstr "" + +#: ../../library/pickle.rst:346 ../../library/pickle.rst:447 +msgid "See :ref:`pickle-persistent` for details and examples of uses." +msgstr "關於細節與用法範例請見 :ref:`pickle-persistent`。" + +#: ../../library/pickle.rst:350 +msgid "" +"A pickler object's dispatch table is a registry of *reduction functions* of " +"the kind which can be declared using :func:`copyreg.pickle`. It is a " +"mapping whose keys are classes and whose values are reduction functions. A " +"reduction function takes a single argument of the associated class and " +"should conform to the same interface as a :meth:`~object.__reduce__` method." +msgstr "" + +#: ../../library/pickle.rst:358 +msgid "" +"By default, a pickler object will not have a :attr:`dispatch_table` " +"attribute, and it will instead use the global dispatch table managed by the :" +"mod:`copyreg` module. However, to customize the pickling for a specific " +"pickler object one can set the :attr:`dispatch_table` attribute to a dict-" +"like object. Alternatively, if a subclass of :class:`Pickler` has a :attr:" +"`dispatch_table` attribute then this will be used as the default dispatch " +"table for instances of that class." +msgstr "" + +#: ../../library/pickle.rst:367 +msgid "See :ref:`pickle-dispatch` for usage examples." +msgstr "關於用法範例請見 :ref:`pickle-dispatch`。" + +#: ../../library/pickle.rst:373 +msgid "" +"Special reducer that can be defined in :class:`Pickler` subclasses. This " +"method has priority over any reducer in the :attr:`dispatch_table`. It " +"should conform to the same interface as a :meth:`~object.__reduce__` method, " +"and can optionally return :data:`NotImplemented` to fallback on :attr:" +"`dispatch_table`-registered reducers to pickle ``obj``." +msgstr "" + +#: ../../library/pickle.rst:379 +msgid "For a detailed example, see :ref:`reducer_override`." +msgstr "" + +#: ../../library/pickle.rst:385 +msgid "" +"Deprecated. Enable fast mode if set to a true value. The fast mode disables " +"the usage of memo, therefore speeding the pickling process by not generating " +"superfluous PUT opcodes. It should not be used with self-referential " +"objects, doing otherwise will cause :class:`Pickler` to recurse infinitely." +msgstr "" + +#: ../../library/pickle.rst:391 +msgid "Use :func:`pickletools.optimize` if you need more compact pickles." +msgstr "" + +#: ../../library/pickle.rst:396 +msgid "This takes a binary file for reading a pickle data stream." +msgstr "" + +#: ../../library/pickle.rst:398 +msgid "" +"The protocol version of the pickle is detected automatically, so no protocol " +"argument is needed." +msgstr "" + +#: ../../library/pickle.rst:401 +msgid "" +"The argument *file* must have three methods, a read() method that takes an " +"integer argument, a readinto() method that takes a buffer argument and a " +"readline() method that requires no arguments, as in the :class:`io." +"BufferedIOBase` interface. Thus *file* can be an on-disk file opened for " +"binary reading, an :class:`io.BytesIO` object, or any other custom object " +"that meets this interface." +msgstr "" + +#: ../../library/pickle.rst:408 +msgid "" +"The optional arguments *fix_imports*, *encoding* and *errors* are used to " +"control compatibility support for pickle stream generated by Python 2. If " +"*fix_imports* is true, pickle will try to map the old Python 2 names to the " +"new names used in Python 3. The *encoding* and *errors* tell pickle how to " +"decode 8-bit string instances pickled by Python 2; these default to 'ASCII' " +"and 'strict', respectively. The *encoding* can be 'bytes' to read these 8-" +"bit string instances as bytes objects. Using ``encoding='latin1'`` is " +"required for unpickling NumPy arrays and instances of :class:`~datetime." +"datetime`, :class:`~datetime.date` and :class:`~datetime.time` pickled by " +"Python 2." +msgstr "" + +#: ../../library/pickle.rst:419 +msgid "" +"If *buffers* is ``None`` (the default), then all data necessary for " +"deserialization must be contained in the pickle stream. This means that the " +"*buffer_callback* argument was ``None`` when a :class:`Pickler` was " +"instantiated (or when :func:`dump` or :func:`dumps` was called)." +msgstr "" + +#: ../../library/pickle.rst:424 +msgid "" +"If *buffers* is not ``None``, it should be an iterable of buffer-enabled " +"objects that is consumed each time the pickle stream references an :ref:`out-" +"of-band ` buffer view. Such buffers have been given in order to " +"the *buffer_callback* of a Pickler object." +msgstr "" + +#: ../../library/pickle.rst:434 +msgid "" +"Read the pickled representation of an object from the open file object given " +"in the constructor, and return the reconstituted object hierarchy specified " +"therein. Bytes past the pickled representation of the object are ignored." +msgstr "" + +#: ../../library/pickle.rst:441 +msgid "Raise an :exc:`UnpicklingError` by default." +msgstr "" + +#: ../../library/pickle.rst:443 +msgid "" +"If defined, :meth:`persistent_load` should return the object specified by " +"the persistent ID *pid*. If an invalid persistent ID is encountered, an :" +"exc:`UnpicklingError` should be raised." +msgstr "" + +#: ../../library/pickle.rst:451 +msgid "" +"Import *module* if necessary and return the object called *name* from it, " +"where the *module* and *name* arguments are :class:`str` objects. Note, " +"unlike its name suggests, :meth:`find_class` is also used for finding " +"functions." +msgstr "" + +#: ../../library/pickle.rst:456 +msgid "" +"Subclasses may override this to gain control over what type of objects and " +"how they can be loaded, potentially reducing security risks. Refer to :ref:" +"`pickle-restrict` for details." +msgstr "" + +#: ../../library/pickle.rst:460 +msgid "" +"Raises an :ref:`auditing event ` ``pickle.find_class`` with " +"arguments ``module``, ``name``." +msgstr "" +"引發一個附帶引數 ``module``、``name`` 的\\ :ref:`稽核事件 ` " +"``pickle.find_class``。" + +#: ../../library/pickle.rst:464 +msgid "" +"A wrapper for a buffer representing picklable data. *buffer* must be a :ref:" +"`buffer-providing ` object, such as a :term:`bytes-like " +"object` or a N-dimensional array." +msgstr "" + +#: ../../library/pickle.rst:468 +msgid "" +":class:`PickleBuffer` is itself a buffer provider, therefore it is possible " +"to pass it to other APIs expecting a buffer-providing object, such as :class:" +"`memoryview`." +msgstr "" + +#: ../../library/pickle.rst:472 +msgid "" +":class:`PickleBuffer` objects can only be serialized using pickle protocol 5 " +"or higher. They are eligible for :ref:`out-of-band serialization `." +msgstr "" + +#: ../../library/pickle.rst:480 +msgid "" +"Return a :class:`memoryview` of the memory area underlying this buffer. The " +"returned object is a one-dimensional, C-contiguous memoryview with format " +"``B`` (unsigned bytes). :exc:`BufferError` is raised if the buffer is " +"neither C- nor Fortran-contiguous." +msgstr "" + +#: ../../library/pickle.rst:487 +msgid "Release the underlying buffer exposed by the PickleBuffer object." +msgstr "" + +#: ../../library/pickle.rst:493 +msgid "What can be pickled and unpickled?" +msgstr "" + +#: ../../library/pickle.rst:495 +msgid "The following types can be pickled:" +msgstr "" + +#: ../../library/pickle.rst:497 +msgid "" +"built-in constants (``None``, ``True``, ``False``, ``Ellipsis``, and :data:" +"`NotImplemented`);" +msgstr "" + +#: ../../library/pickle.rst:500 +msgid "integers, floating-point numbers, complex numbers;" +msgstr "" + +#: ../../library/pickle.rst:502 +msgid "strings, bytes, bytearrays;" +msgstr "" + +#: ../../library/pickle.rst:504 +msgid "" +"tuples, lists, sets, and dictionaries containing only picklable objects;" +msgstr "" + +#: ../../library/pickle.rst:506 +msgid "" +"functions (built-in and user-defined) accessible from the top level of a " +"module (using :keyword:`def`, not :keyword:`lambda`);" +msgstr "" + +#: ../../library/pickle.rst:509 +msgid "classes accessible from the top level of a module;" +msgstr "" + +#: ../../library/pickle.rst:511 +msgid "" +"instances of such classes whose the result of calling :meth:`~object." +"__getstate__` is picklable (see section :ref:`pickle-inst` for details)." +msgstr "" + +#: ../../library/pickle.rst:514 +msgid "" +"Attempts to pickle unpicklable objects will raise the :exc:`PicklingError` " +"exception; when this happens, an unspecified number of bytes may have " +"already been written to the underlying file. Trying to pickle a highly " +"recursive data structure may exceed the maximum recursion depth, a :exc:" +"`RecursionError` will be raised in this case. You can carefully raise this " +"limit with :func:`sys.setrecursionlimit`." +msgstr "" + +#: ../../library/pickle.rst:521 +msgid "" +"Note that functions (built-in and user-defined) are pickled by fully :term:" +"`qualified name`, not by value. [#]_ This means that only the function name " +"is pickled, along with the name of the containing module and classes. " +"Neither the function's code, nor any of its function attributes are " +"pickled. Thus the defining module must be importable in the unpickling " +"environment, and the module must contain the named object, otherwise an " +"exception will be raised. [#]_" +msgstr "" + +#: ../../library/pickle.rst:528 +msgid "" +"Similarly, classes are pickled by fully qualified name, so the same " +"restrictions in the unpickling environment apply. Note that none of the " +"class's code or data is pickled, so in the following example the class " +"attribute ``attr`` is not restored in the unpickling environment::" +msgstr "" + +#: ../../library/pickle.rst:538 +msgid "" +"These restrictions are why picklable functions and classes must be defined " +"at the top level of a module." +msgstr "" + +#: ../../library/pickle.rst:541 +msgid "" +"Similarly, when class instances are pickled, their class's code and data are " +"not pickled along with them. Only the instance data are pickled. This is " +"done on purpose, so you can fix bugs in a class or add methods to the class " +"and still load objects that were created with an earlier version of the " +"class. If you plan to have long-lived objects that will see many versions " +"of a class, it may be worthwhile to put a version number in the objects so " +"that suitable conversions can be made by the class's :meth:`~object." +"__setstate__` method." +msgstr "" + +#: ../../library/pickle.rst:553 +msgid "Pickling Class Instances" +msgstr "" + +#: ../../library/pickle.rst:557 +msgid "" +"In this section, we describe the general mechanisms available to you to " +"define, customize, and control how class instances are pickled and unpickled." +msgstr "" + +#: ../../library/pickle.rst:560 +msgid "" +"In most cases, no additional code is needed to make instances picklable. By " +"default, pickle will retrieve the class and the attributes of an instance " +"via introspection. When a class instance is unpickled, its :meth:`~object." +"__init__` method is usually *not* invoked. The default behaviour first " +"creates an uninitialized instance and then restores the saved attributes. " +"The following code shows an implementation of this behaviour::" +msgstr "" + +#: ../../library/pickle.rst:575 +msgid "" +"Classes can alter the default behaviour by providing one or several special " +"methods:" +msgstr "" + +#: ../../library/pickle.rst:580 +msgid "" +"In protocols 2 and newer, classes that implements the :meth:" +"`__getnewargs_ex__` method can dictate the values passed to the :meth:" +"`__new__` method upon unpickling. The method must return a pair ``(args, " +"kwargs)`` where *args* is a tuple of positional arguments and *kwargs* a " +"dictionary of named arguments for constructing the object. Those will be " +"passed to the :meth:`__new__` method upon unpickling." +msgstr "" + +#: ../../library/pickle.rst:588 +msgid "" +"You should implement this method if the :meth:`__new__` method of your class " +"requires keyword-only arguments. Otherwise, it is recommended for " +"compatibility to implement :meth:`__getnewargs__`." +msgstr "" + +#: ../../library/pickle.rst:592 +msgid ":meth:`__getnewargs_ex__` is now used in protocols 2 and 3." +msgstr "" + +#: ../../library/pickle.rst:598 +msgid "" +"This method serves a similar purpose as :meth:`__getnewargs_ex__`, but " +"supports only positional arguments. It must return a tuple of arguments " +"``args`` which will be passed to the :meth:`__new__` method upon unpickling." +msgstr "" + +#: ../../library/pickle.rst:602 +msgid "" +":meth:`__getnewargs__` will not be called if :meth:`__getnewargs_ex__` is " +"defined." +msgstr "" + +#: ../../library/pickle.rst:605 +msgid "" +"Before Python 3.6, :meth:`__getnewargs__` was called instead of :meth:" +"`__getnewargs_ex__` in protocols 2 and 3." +msgstr "" + +#: ../../library/pickle.rst:612 +msgid "" +"Classes can further influence how their instances are pickled by overriding " +"the method :meth:`__getstate__`. It is called and the returned object is " +"pickled as the contents for the instance, instead of a default state. There " +"are several cases:" +msgstr "" + +#: ../../library/pickle.rst:617 +msgid "" +"For a class that has no instance :attr:`~object.__dict__` and no :attr:" +"`~object.__slots__`, the default state is ``None``." +msgstr "" + +#: ../../library/pickle.rst:620 +msgid "" +"For a class that has an instance :attr:`~object.__dict__` and no :attr:" +"`~object.__slots__`, the default state is ``self.__dict__``." +msgstr "" + +#: ../../library/pickle.rst:623 +msgid "" +"For a class that has an instance :attr:`~object.__dict__` and :attr:`~object." +"__slots__`, the default state is a tuple consisting of two dictionaries: " +"``self.__dict__``, and a dictionary mapping slot names to slot values. Only " +"slots that have a value are included in the latter." +msgstr "" + +#: ../../library/pickle.rst:629 +msgid "" +"For a class that has :attr:`~object.__slots__` and no instance :attr:" +"`~object.__dict__`, the default state is a tuple whose first item is " +"``None`` and whose second item is a dictionary mapping slot names to slot " +"values described in the previous bullet." +msgstr "" + +#: ../../library/pickle.rst:634 +msgid "" +"Added the default implementation of the ``__getstate__()`` method in the :" +"class:`object` class." +msgstr "" + +#: ../../library/pickle.rst:641 +msgid "" +"Upon unpickling, if the class defines :meth:`__setstate__`, it is called " +"with the unpickled state. In that case, there is no requirement for the " +"state object to be a dictionary. Otherwise, the pickled state must be a " +"dictionary and its items are assigned to the new instance's dictionary." +msgstr "" + +#: ../../library/pickle.rst:648 +msgid "" +"If :meth:`__reduce__` returns a state with value ``None`` at pickling, the :" +"meth:`__setstate__` method will not be called upon unpickling." +msgstr "" + +#: ../../library/pickle.rst:652 +msgid "" +"Refer to the section :ref:`pickle-state` for more information about how to " +"use the methods :meth:`~object.__getstate__` and :meth:`~object." +"__setstate__`." +msgstr "" + +#: ../../library/pickle.rst:657 +msgid "" +"At unpickling time, some methods like :meth:`~object.__getattr__`, :meth:" +"`~object.__getattribute__`, or :meth:`~object.__setattr__` may be called " +"upon the instance. In case those methods rely on some internal invariant " +"being true, the type should implement :meth:`~object.__new__` to establish " +"such an invariant, as :meth:`~object.__init__` is not called when unpickling " +"an instance." +msgstr "" + +#: ../../library/pickle.rst:666 +msgid "" +"As we shall see, pickle does not use directly the methods described above. " +"In fact, these methods are part of the copy protocol which implements the :" +"meth:`~object.__reduce__` special method. The copy protocol provides a " +"unified interface for retrieving the data necessary for pickling and copying " +"objects. [#]_" +msgstr "" + +#: ../../library/pickle.rst:672 +msgid "" +"Although powerful, implementing :meth:`~object.__reduce__` directly in your " +"classes is error prone. For this reason, class designers should use the " +"high-level interface (i.e., :meth:`~object.__getnewargs_ex__`, :meth:" +"`~object.__getstate__` and :meth:`~object.__setstate__`) whenever possible. " +"We will show, however, cases where using :meth:`!__reduce__` is the only " +"option or leads to more efficient pickling or both." +msgstr "" + +#: ../../library/pickle.rst:681 +msgid "" +"The interface is currently defined as follows. The :meth:`__reduce__` " +"method takes no argument and shall return either a string or preferably a " +"tuple (the returned object is often referred to as the \"reduce value\")." +msgstr "" + +#: ../../library/pickle.rst:685 +msgid "" +"If a string is returned, the string should be interpreted as the name of a " +"global variable. It should be the object's local name relative to its " +"module; the pickle module searches the module namespace to determine the " +"object's module. This behaviour is typically useful for singletons." +msgstr "" + +#: ../../library/pickle.rst:690 +msgid "" +"When a tuple is returned, it must be between two and six items long. " +"Optional items can either be omitted, or ``None`` can be provided as their " +"value. The semantics of each item are in order:" +msgstr "" + +#: ../../library/pickle.rst:696 +msgid "" +"A callable object that will be called to create the initial version of the " +"object." +msgstr "" + +#: ../../library/pickle.rst:699 +msgid "" +"A tuple of arguments for the callable object. An empty tuple must be given " +"if the callable does not accept any argument." +msgstr "" + +#: ../../library/pickle.rst:702 +msgid "" +"Optionally, the object's state, which will be passed to the object's :meth:" +"`__setstate__` method as previously described. If the object has no such " +"method then, the value must be a dictionary and it will be added to the " +"object's :attr:`~object.__dict__` attribute." +msgstr "" + +#: ../../library/pickle.rst:707 +msgid "" +"Optionally, an iterator (and not a sequence) yielding successive items. " +"These items will be appended to the object either using ``obj.append(item)`` " +"or, in batch, using ``obj.extend(list_of_items)``. This is primarily used " +"for list subclasses, but may be used by other classes as long as they have :" +"ref:`append and extend methods ` with the appropriate " +"signature. (Whether :meth:`!append` or :meth:`!extend` is used depends on " +"which pickle protocol version is used as well as the number of items to " +"append, so both must be supported.)" +msgstr "" + +#: ../../library/pickle.rst:717 +msgid "" +"Optionally, an iterator (not a sequence) yielding successive key-value " +"pairs. These items will be stored to the object using ``obj[key] = " +"value``. This is primarily used for dictionary subclasses, but may be used " +"by other classes as long as they implement :meth:`__setitem__`." +msgstr "" + +#: ../../library/pickle.rst:722 +msgid "" +"Optionally, a callable with a ``(obj, state)`` signature. This callable " +"allows the user to programmatically control the state-updating behavior of a " +"specific object, instead of using ``obj``'s static :meth:`__setstate__` " +"method. If not ``None``, this callable will have priority over ``obj``'s :" +"meth:`__setstate__`." +msgstr "" + +#: ../../library/pickle.rst:728 +msgid "The optional sixth tuple item, ``(obj, state)``, was added." +msgstr "" + +#: ../../library/pickle.rst:734 +msgid "" +"Alternatively, a :meth:`__reduce_ex__` method may be defined. The only " +"difference is this method should take a single integer argument, the " +"protocol version. When defined, pickle will prefer it over the :meth:" +"`__reduce__` method. In addition, :meth:`__reduce__` automatically becomes " +"a synonym for the extended version. The main use for this method is to " +"provide backwards-compatible reduce values for older Python releases." +msgstr "" + +#: ../../library/pickle.rst:746 +msgid "Persistence of External Objects" +msgstr "" + +#: ../../library/pickle.rst:752 +msgid "" +"For the benefit of object persistence, the :mod:`pickle` module supports the " +"notion of a reference to an object outside the pickled data stream. Such " +"objects are referenced by a persistent ID, which should be either a string " +"of alphanumeric characters (for protocol 0) [#]_ or just an arbitrary object " +"(for any newer protocol)." +msgstr "" + +#: ../../library/pickle.rst:758 +msgid "" +"The resolution of such persistent IDs is not defined by the :mod:`pickle` " +"module; it will delegate this resolution to the user-defined methods on the " +"pickler and unpickler, :meth:`~Pickler.persistent_id` and :meth:`~Unpickler." +"persistent_load` respectively." +msgstr "" + +#: ../../library/pickle.rst:763 +msgid "" +"To pickle objects that have an external persistent ID, the pickler must have " +"a custom :meth:`~Pickler.persistent_id` method that takes an object as an " +"argument and returns either ``None`` or the persistent ID for that object. " +"When ``None`` is returned, the pickler simply pickles the object as normal. " +"When a persistent ID string is returned, the pickler will pickle that " +"object, along with a marker so that the unpickler will recognize it as a " +"persistent ID." +msgstr "" + +#: ../../library/pickle.rst:770 +msgid "" +"To unpickle external objects, the unpickler must have a custom :meth:" +"`~Unpickler.persistent_load` method that takes a persistent ID object and " +"returns the referenced object." +msgstr "" + +#: ../../library/pickle.rst:774 +msgid "" +"Here is a comprehensive example presenting how persistent ID can be used to " +"pickle external objects by reference." +msgstr "" + +#: ../../library/pickle.rst:782 +msgid "Dispatch Tables" +msgstr "" + +#: ../../library/pickle.rst:784 +msgid "" +"If one wants to customize pickling of some classes without disturbing any " +"other code which depends on pickling, then one can create a pickler with a " +"private dispatch table." +msgstr "" + +#: ../../library/pickle.rst:788 +msgid "" +"The global dispatch table managed by the :mod:`copyreg` module is available " +"as :data:`!copyreg.dispatch_table`. Therefore, one may choose to use a " +"modified copy of :data:`!copyreg.dispatch_table` as a private dispatch table." +msgstr "" + +#: ../../library/pickle.rst:793 +msgid "For example ::" +msgstr "舉例來說： ::" + +#: ../../library/pickle.rst:800 +msgid "" +"creates an instance of :class:`pickle.Pickler` with a private dispatch table " +"which handles the ``SomeClass`` class specially. Alternatively, the code ::" +msgstr "" + +#: ../../library/pickle.rst:810 +msgid "" +"does the same but all instances of ``MyPickler`` will by default share the " +"private dispatch table. On the other hand, the code ::" +msgstr "" + +#: ../../library/pickle.rst:817 +msgid "" +"modifies the global dispatch table shared by all users of the :mod:`copyreg` " +"module." +msgstr "" + +#: ../../library/pickle.rst:822 +msgid "Handling Stateful Objects" +msgstr "" + +#: ../../library/pickle.rst:828 +msgid "" +"Here's an example that shows how to modify pickling behavior for a class. " +"The :class:`!TextReader` class below opens a text file, and returns the line " +"number and line contents each time its :meth:`!readline` method is called. " +"If a :class:`!TextReader` instance is pickled, all attributes *except* the " +"file object member are saved. When the instance is unpickled, the file is " +"reopened, and reading resumes from the last location. The :meth:`!" +"__setstate__` and :meth:`!__getstate__` methods are used to implement this " +"behavior. ::" +msgstr "" + +#: ../../library/pickle.rst:874 +msgid "A sample usage might be something like this::" +msgstr "" + +#: ../../library/pickle.rst:888 +msgid "Custom Reduction for Types, Functions, and Other Objects" +msgstr "" + +#: ../../library/pickle.rst:892 +msgid "" +"Sometimes, :attr:`~Pickler.dispatch_table` may not be flexible enough. In " +"particular we may want to customize pickling based on another criterion than " +"the object's type, or we may want to customize the pickling of functions and " +"classes." +msgstr "" + +#: ../../library/pickle.rst:897 +msgid "" +"For those cases, it is possible to subclass from the :class:`Pickler` class " +"and implement a :meth:`~Pickler.reducer_override` method. This method can " +"return an arbitrary reduction tuple (see :meth:`~object.__reduce__`). It can " +"alternatively return :data:`NotImplemented` to fallback to the traditional " +"behavior." +msgstr "" + +#: ../../library/pickle.rst:902 +msgid "" +"If both the :attr:`~Pickler.dispatch_table` and :meth:`~Pickler." +"reducer_override` are defined, then :meth:`~Pickler.reducer_override` method " +"takes priority." +msgstr "" + +#: ../../library/pickle.rst:907 +msgid "" +"For performance reasons, :meth:`~Pickler.reducer_override` may not be called " +"for the following objects: ``None``, ``True``, ``False``, and exact " +"instances of :class:`int`, :class:`float`, :class:`bytes`, :class:`str`, :" +"class:`dict`, :class:`set`, :class:`frozenset`, :class:`list` and :class:" +"`tuple`." +msgstr "" + +#: ../../library/pickle.rst:913 +msgid "" +"Here is a simple example where we allow pickling and reconstructing a given " +"class::" +msgstr "" + +#: ../../library/pickle.rst:948 +msgid "Out-of-band Buffers" +msgstr "" + +#: ../../library/pickle.rst:952 +msgid "" +"In some contexts, the :mod:`pickle` module is used to transfer massive " +"amounts of data. Therefore, it can be important to minimize the number of " +"memory copies, to preserve performance and resource consumption. However, " +"normal operation of the :mod:`pickle` module, as it transforms a graph-like " +"structure of objects into a sequential stream of bytes, intrinsically " +"involves copying data to and from the pickle stream." +msgstr "" + +#: ../../library/pickle.rst:959 +msgid "" +"This constraint can be eschewed if both the *provider* (the implementation " +"of the object types to be transferred) and the *consumer* (the " +"implementation of the communications system) support the out-of-band " +"transfer facilities provided by pickle protocol 5 and higher." +msgstr "" + +#: ../../library/pickle.rst:965 +msgid "Provider API" +msgstr "" + +#: ../../library/pickle.rst:967 +msgid "" +"The large data objects to be pickled must implement a :meth:`~object." +"__reduce_ex__` method specialized for protocol 5 and higher, which returns " +"a :class:`PickleBuffer` instance (instead of e.g. a :class:`bytes` object) " +"for any large data." +msgstr "" + +#: ../../library/pickle.rst:972 +msgid "" +"A :class:`PickleBuffer` object *signals* that the underlying buffer is " +"eligible for out-of-band data transfer. Those objects remain compatible " +"with normal usage of the :mod:`pickle` module. However, consumers can also " +"opt-in to tell :mod:`pickle` that they will handle those buffers by " +"themselves." +msgstr "" + +#: ../../library/pickle.rst:979 +msgid "Consumer API" +msgstr "" + +#: ../../library/pickle.rst:981 +msgid "" +"A communications system can enable custom handling of the :class:" +"`PickleBuffer` objects generated when serializing an object graph." +msgstr "" + +#: ../../library/pickle.rst:984 +msgid "" +"On the sending side, it needs to pass a *buffer_callback* argument to :class:" +"`Pickler` (or to the :func:`dump` or :func:`dumps` function), which will be " +"called with each :class:`PickleBuffer` generated while pickling the object " +"graph. Buffers accumulated by the *buffer_callback* will not see their data " +"copied into the pickle stream, only a cheap marker will be inserted." +msgstr "" + +#: ../../library/pickle.rst:991 +msgid "" +"On the receiving side, it needs to pass a *buffers* argument to :class:" +"`Unpickler` (or to the :func:`load` or :func:`loads` function), which is an " +"iterable of the buffers which were passed to *buffer_callback*. That " +"iterable should produce buffers in the same order as they were passed to " +"*buffer_callback*. Those buffers will provide the data expected by the " +"reconstructors of the objects whose pickling produced the original :class:" +"`PickleBuffer` objects." +msgstr "" + +#: ../../library/pickle.rst:999 +msgid "" +"Between the sending side and the receiving side, the communications system " +"is free to implement its own transfer mechanism for out-of-band buffers. " +"Potential optimizations include the use of shared memory or datatype-" +"dependent compression." +msgstr "" + +#: ../../library/pickle.rst:1005 +msgid "Example" +msgstr "範例" + +#: ../../library/pickle.rst:1007 +msgid "" +"Here is a trivial example where we implement a :class:`bytearray` subclass " +"able to participate in out-of-band buffer pickling::" +msgstr "" + +#: ../../library/pickle.rst:1031 +msgid "" +"The reconstructor (the ``_reconstruct`` class method) returns the buffer's " +"providing object if it has the right type. This is an easy way to simulate " +"zero-copy behaviour on this toy example." +msgstr "" + +#: ../../library/pickle.rst:1035 +msgid "" +"On the consumer side, we can pickle those objects the usual way, which when " +"unserialized will give us a copy of the original object::" +msgstr "" + +#: ../../library/pickle.rst:1044 +msgid "" +"But if we pass a *buffer_callback* and then give back the accumulated " +"buffers when unserializing, we are able to get back the original object::" +msgstr "" + +#: ../../library/pickle.rst:1054 +msgid "" +"This example is limited by the fact that :class:`bytearray` allocates its " +"own memory: you cannot create a :class:`bytearray` instance that is backed " +"by another object's memory. However, third-party datatypes such as NumPy " +"arrays do not have this limitation, and allow use of zero-copy pickling (or " +"making as few copies as possible) when transferring between distinct " +"processes or systems." +msgstr "" + +#: ../../library/pickle.rst:1061 +msgid ":pep:`574` -- Pickle protocol 5 with out-of-band data" +msgstr "" + +#: ../../library/pickle.rst:1067 +msgid "Restricting Globals" +msgstr "" + +#: ../../library/pickle.rst:1072 +msgid "" +"By default, unpickling will import any class or function that it finds in " +"the pickle data. For many applications, this behaviour is unacceptable as " +"it permits the unpickler to import and invoke arbitrary code. Just consider " +"what this hand-crafted pickle data stream does when loaded::" +msgstr "" + +#: ../../library/pickle.rst:1082 +msgid "" +"In this example, the unpickler imports the :func:`os.system` function and " +"then apply the string argument \"echo hello world\". Although this example " +"is inoffensive, it is not difficult to imagine one that could damage your " +"system." +msgstr "" + +#: ../../library/pickle.rst:1086 +msgid "" +"For this reason, you may want to control what gets unpickled by customizing :" +"meth:`Unpickler.find_class`. Unlike its name suggests, :meth:`Unpickler." +"find_class` is called whenever a global (i.e., a class or a function) is " +"requested. Thus it is possible to either completely forbid globals or " +"restrict them to a safe subset." +msgstr "" + +#: ../../library/pickle.rst:1092 +msgid "" +"Here is an example of an unpickler allowing only few safe classes from the :" +"mod:`builtins` module to be loaded::" +msgstr "" + +#: ../../library/pickle.rst:1121 +msgid "A sample usage of our unpickler working as intended::" +msgstr "" + +#: ../../library/pickle.rst:1140 +msgid "" +"As our examples shows, you have to be careful with what you allow to be " +"unpickled. Therefore if security is a concern, you may want to consider " +"alternatives such as the marshalling API in :mod:`xmlrpc.client` or third-" +"party solutions." +msgstr "" + +#: ../../library/pickle.rst:1147 +msgid "Performance" +msgstr "" + +#: ../../library/pickle.rst:1149 +msgid "" +"Recent versions of the pickle protocol (from protocol 2 and upwards) feature " +"efficient binary encodings for several common features and built-in types. " +"Also, the :mod:`pickle` module has a transparent optimizer written in C." +msgstr "" + +#: ../../library/pickle.rst:1157 +msgid "Examples" +msgstr "範例" + +#: ../../library/pickle.rst:1159 +msgid "" +"For the simplest code, use the :func:`dump` and :func:`load` functions. ::" +msgstr "" + +#: ../../library/pickle.rst:1175 +msgid "The following example reads the resulting pickled data. ::" +msgstr "" + +#: ../../library/pickle.rst:1191 +msgid "Module :mod:`copyreg`" +msgstr ":mod:`copyreg` 模組" + +#: ../../library/pickle.rst:1192 +msgid "Pickle interface constructor registration for extension types." +msgstr "" + +#: ../../library/pickle.rst:1194 +msgid "Module :mod:`pickletools`" +msgstr ":mod:`pickletools` 模組" + +#: ../../library/pickle.rst:1195 +msgid "Tools for working with and analyzing pickled data." +msgstr "" + +#: ../../library/pickle.rst:1197 +msgid "Module :mod:`shelve`" +msgstr ":mod:`shelve` 模組" + +#: ../../library/pickle.rst:1198 +msgid "Indexed databases of objects; uses :mod:`pickle`." +msgstr "" + +#: ../../library/pickle.rst:1200 +msgid "Module :mod:`copy`" +msgstr ":mod:`copy` 模組" + +#: ../../library/pickle.rst:1201 +msgid "Shallow and deep object copying." +msgstr "" + +#: ../../library/pickle.rst:1203 +msgid "Module :mod:`marshal`" +msgstr ":mod:`marshal` 模組" + +#: ../../library/pickle.rst:1204 +msgid "High-performance serialization of built-in types." +msgstr "" + +#: ../../library/pickle.rst:1208 +msgid "Footnotes" +msgstr "註解" + +#: ../../library/pickle.rst:1209 +msgid "Don't confuse this with the :mod:`marshal` module" +msgstr "" + +#: ../../library/pickle.rst:1211 +msgid "" +"This is why :keyword:`lambda` functions cannot be pickled: all :keyword:`!" +"lambda` functions share the same name: ````." +msgstr "" + +#: ../../library/pickle.rst:1214 +msgid "" +"The exception raised will likely be an :exc:`ImportError` or an :exc:" +"`AttributeError` but it could be something else." +msgstr "" + +#: ../../library/pickle.rst:1217 +msgid "" +"The :mod:`copy` module uses this protocol for shallow and deep copying " +"operations." +msgstr "" + +#: ../../library/pickle.rst:1220 +msgid "" +"The limitation on alphanumeric characters is due to the fact that persistent " +"IDs in protocol 0 are delimited by the newline character. Therefore if any " +"kind of newline characters occurs in persistent IDs, the resulting pickled " +"data will become unreadable." +msgstr "" + +#: ../../library/pickle.rst:12 +msgid "persistence" +msgstr "persistence（持續性）" + +#: ../../library/pickle.rst:12 +msgid "persistent" +msgstr "persistent（持續）" + +#: ../../library/pickle.rst:12 +msgid "objects" +msgstr "objects（物件）" + +#: ../../library/pickle.rst:12 +msgid "serializing" +msgstr "serializing（序列化）" + +#: ../../library/pickle.rst:12 +msgid "marshalling" +msgstr "marshalling" + +#: ../../library/pickle.rst:12 +msgid "flattening" +msgstr "flattening（攤平）" + +#: ../../library/pickle.rst:12 +msgid "pickling" +msgstr "pickling" + +#: ../../library/pickle.rst:123 +msgid "External Data Representation" +msgstr "External Data Representation（外部資料表示法）" + +#: ../../library/pickle.rst:664 +msgid "copy" +msgstr "copy（複製）" + +#: ../../library/pickle.rst:664 +msgid "protocol" +msgstr "protocol（協定）" + +#: ../../library/pickle.rst:748 +msgid "persistent_id (pickle protocol)" +msgstr "persistent_id（pickle 協定）" + +#: ../../library/pickle.rst:748 +msgid "persistent_load (pickle protocol)" +msgstr "persistent_load（pickle 協定）" + +#: ../../library/pickle.rst:824 +msgid "__getstate__() (copy protocol)" +msgstr "__getstate__()（copy 協定）" + +#: ../../library/pickle.rst:824 +msgid "__setstate__() (copy protocol)" +msgstr "__setstate__()（copy 協定）" + +#: ../../library/pickle.rst:1069 +msgid "find_class() (pickle protocol)" +msgstr "find_class()（pickle 協定）" From cce719e0815985c8d39d2c615a6b0887eb7dff63 Mon Sep 17 00:00:00 2001 From: "Raynor@GullU" Date: Thu, 22 Aug 2024 00:34:46 +0800 Subject: [PATCH 05/17] docs(library/pickle.po): editing, up to line 525 --- library/pickle.po | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/library/pickle.po b/library/pickle.po index 8c05090630..e88ad44209 100644 --- a/library/pickle.po +++ b/library/pickle.po @@ -470,40 +470,49 @@ msgid "" "Return the reconstituted object hierarchy of the pickled representation " "*data* of an object. *data* must be a :term:`bytes-like object`." msgstr "" +"回傳從 *data* 的 pickle 封包重建後的物件階層。*data* 必須是一個 :term:`bytes-" +"like object`。" #: ../../library/pickle.rst:264 msgid "" "Arguments *fix_imports*, *encoding*, *errors*, *strict* and *buffers* have " "the same meaning as in the :class:`Unpickler` constructor." msgstr "" +"引數 *fix_imports*、*encoding*、*errors*、*strict* 和 *buffers* 的意義與 :" +"class:`Unpickler` 建構式所用的相同。" #: ../../library/pickle.rst:271 msgid "The :mod:`pickle` module defines three exceptions:" -msgstr "" +msgstr ":mod:`pickle` 模組定義了以下三種例外：" #: ../../library/pickle.rst:275 msgid "" "Common base class for the other pickling exceptions. It inherits from :exc:" "`Exception`." msgstr "" +"繼承 :exc:`Exception` 類別。一個在封裝或拆封時遭遇其他例外時通用的基底類別。" #: ../../library/pickle.rst:280 msgid "" "Error raised when an unpicklable object is encountered by :class:`Pickler`. " "It inherits from :exc:`PickleError`." msgstr "" +"當 :class:`Pickler` 遭遇無法封裝物件時會引發的例外。繼承 :exc:`PickleError` " +"類別。" #: ../../library/pickle.rst:283 msgid "" "Refer to :ref:`pickle-picklable` to learn what kinds of objects can be " "pickled." -msgstr "" +msgstr "請參閱 :ref:`pickle-picklable` 以了解哪些物件是可以被封裝的。" #: ../../library/pickle.rst:288 msgid "" "Error raised when there is a problem unpickling an object, such as a data " "corruption or a security violation. It inherits from :exc:`PickleError`." msgstr "" +"拆封物件時遇到問題（如資料毀損或違反安全性原則等）所引發的意外。繼承自 :exc:" +"`PickleError` 類別。" #: ../../library/pickle.rst:291 msgid "" @@ -511,6 +520,8 @@ msgid "" "(but not necessarily limited to) AttributeError, EOFError, ImportError, and " "IndexError." msgstr "" +"拆封的時候還是可能會遭遇其他不在此列的例外（例如：AttributeError、EOFError、" +"ImportError、或 IndexError），請注意。" #: ../../library/pickle.rst:296 msgid "" From 8fd17f0895bee0495a0cfdc9a6b5355a57f86166 Mon Sep 17 00:00:00 2001 From: "Raynor@GullU" Date: Fri, 23 Aug 2024 01:46:55 +0800 Subject: [PATCH 06/17] docs(library/pickle.po): editing, up to line 627 --- library/pickle.po | 30 ++++++++++++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/library/pickle.po b/library/pickle.po index e88ad44209..fdd7607b46 100644 --- a/library/pickle.po +++ b/library/pickle.po @@ -528,10 +528,12 @@ msgid "" "The :mod:`pickle` module exports three classes, :class:`Pickler`, :class:" "`Unpickler` and :class:`PickleBuffer`:" msgstr "" +"引入模組 :mod:`pickle` 時會帶來三個類別：:class:`Pickler`、:class:" +"`Unpickler` 和 :class:`PickleBuffer`：" #: ../../library/pickle.rst:301 msgid "This takes a binary file for writing a pickle data stream." -msgstr "" +msgstr "接受一個用以寫入 pickle 資料流的二進位檔案。" #: ../../library/pickle.rst:303 msgid "" @@ -540,6 +542,9 @@ msgid "" "not specified, the default is :data:`DEFAULT_PROTOCOL`. If a negative " "number is specified, :data:`HIGHEST_PROTOCOL` is selected." msgstr "" +"可選引數 *protocol* 接受整數，用來要求封裝器（pickler）使用指定的協定；支援" +"從 0 版起到 :data:`HIGHEST_PROTOCOL` 版的協定。如未指定，則預設為 :data:" +"`DEFAULT_PROTOCOL`。若指定了負數，則視為選擇 :data:`HIGHEST_PROTOCOL`。" #: ../../library/pickle.rst:308 msgid "" @@ -548,6 +553,9 @@ msgid "" "class:`io.BytesIO` instance, or any other custom object that meets this " "interface." msgstr "" +"傳予引數 *file* 的物件必須支援可寫入單一位元組的 write() 方法。只要滿足此條" +"件，傳入的物件可以是一個硬碟上二進位檔案、一個 :class:`io.BytesIO` 實例或任何" +"其他滿足這個介面要求的物件。" #: ../../library/pickle.rst:313 msgid "" @@ -555,12 +563,18 @@ msgid "" "map the new Python 3 names to the old module names used in Python 2, so that " "the pickle data stream is readable with Python 2." msgstr "" +"若 *fix_imports* 設為 true 且 *protocol* 版本小於 3，本模組會嘗試將 Python 3 " +"的新模組名稱轉換為 Python 2 所支援的舊名，以讓 Python 2 能正確地讀取此資料" +"流。" +# SkyLull: 以下幾個關於 buffer_callback 的翻譯需要進一步的校對。何謂out-of-band? buffer view 應作何翻譯？ #: ../../library/pickle.rst:317 msgid "" "If *buffer_callback* is ``None`` (the default), buffer views are serialized " "into *file* as part of the pickle stream." msgstr "" +"如果 *buffer_callback* 是 ``None`` （預設值），緩衝區的視圖會作為 pickle 封裝" +"串流的一部分被序列化進 *file* 中。" #: ../../library/pickle.rst:320 msgid "" @@ -569,22 +583,30 @@ msgid "" "``None``), the given buffer is :ref:`out-of-band `; otherwise " "the buffer is serialized in-band, i.e. inside the pickle stream." msgstr "" +"如果 *buffer_callback* 不是 ``None``，則它可以被多次呼叫並傳遞一個緩衝區的視" +"圖。如果回呼函數回傳一個假值（例如 ``None``），則所給的緩衝區將被視為 :ref:`" +"帶外資料 `；否則，該緩衝區將被視為 pickle 串流的帶內資料被序列" +"化。" #: ../../library/pickle.rst:325 msgid "" "It is an error if *buffer_callback* is not ``None`` and *protocol* is " "``None`` or smaller than 5." msgstr "" +"如果 *buffer_callback* 不是 ``None`` 且 *protocol* 是 ``None`` 或小於 5 則會" +"報錯。" #: ../../library/pickle.rst:333 msgid "" "Write the pickled representation of *obj* to the open file object given in " "the constructor." -msgstr "" +msgstr "將已封裝（pickled）的 *obj* 寫入已在建構式中開啟的對應檔案。" #: ../../library/pickle.rst:338 msgid "Do nothing by default. This exists so a subclass can override it." msgstr "" +"預設不進行任何動作。這是一種抽象方法，用於讓後續繼承這個類別的物件可以覆寫本" +"方法函數。" #: ../../library/pickle.rst:340 msgid "" @@ -594,6 +616,10 @@ msgid "" "defined by :meth:`Unpickler.persistent_load`. Note that the value returned " "by :meth:`persistent_id` cannot itself have a persistent ID." msgstr "" +"如果 :meth:`persistent_id` 回傳 ``None``，則 *obj* 會照一般的方式進行封裝" +"（pickling）。若回傳其他值，則 :class:`Pickler` 會將該值作為 *obj* 的永久識別" +"碼回傳。此永久識別碼的意義應由 :meth:`Unpickler.persistent_load` 定義。請注" +"意 :meth:`persistent_id` 回傳的值本身不能擁有自己的永久識別碼。" #: ../../library/pickle.rst:346 ../../library/pickle.rst:447 msgid "See :ref:`pickle-persistent` for details and examples of uses." From b87ff2c37217cf55031537c2148133a317af33d2 Mon Sep 17 00:00:00 2001 From: "Raynor@GullU" Date: Sat, 24 Aug 2024 17:50:15 +0800 Subject: [PATCH 07/17] docs(library/pickle.po): editing, up to line 778 --- library/pickle.po | 78 +++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 65 insertions(+), 13 deletions(-) diff --git a/library/pickle.po b/library/pickle.po index fdd7607b46..102d770848 100644 --- a/library/pickle.po +++ b/library/pickle.po @@ -194,7 +194,9 @@ msgstr "" "JSON 具有高互通性（interoperability）且在 Python 以外的環境也被大量利用，但 " "pickle 只能在 Python 內使用。" -# Skylull: introspection, introspection facilities +# Skylull: [t] +# introspection -> 自省 +# introspection facilities -> 自省措施 # https://zh.wikipedia.org/wiki/%E5%86%85%E7%9C%81_(%E8%AE%A1%E7%AE%97%E6%9C%BA%E7%A7%91%E5%AD%A6) # https://book.pythontips.com/en/latest/object_introspection.html # https://www.geeksforgeeks.org/code-introspection-in-python/ @@ -207,7 +209,7 @@ msgid "" "`specific object APIs `);" msgstr "" "預設狀態下的 JSON 只能紀錄一小部份的 Python 內建型別，且無法紀錄自訂類別；但" -"透過 Python 的自省功能，pickle 可以紀錄絕大多數的 Python 型別（其他比較複雜的" +"透過 Python 的自省措施，pickle 可以紀錄絕大多數的 Python 型別（其他比較複雜的" "狀況也可以透過實作 :ref:`specific object APIs ` 來解決）；" #: ../../library/pickle.rst:110 @@ -321,6 +323,13 @@ msgstr "" "版本 5 的協定在 Python 3.8 被新增。現在能支援帶外資料（Out-of-band data）並加" "速帶內資料的處理速度。請參閱 :pep:`574` 以了解第 5 版協定改進的細節。" +# SkyLull: [t] +# persistent -> 持久 +# data persistent -> 資料持久化 +# https://zh.wikipedia.org/zh- +# tw/%E5%8F%AF%E6%8C%81%E4%B9%85%E5%8C%96%E6%95%B0%E6%8D%AE%E7%BB%93%E6%9E%84 +# https://1fly2sky.wordpress.com/2016/04/05/%E6%8C%81%E4%B9%85%E5%B1%A4data- +# persistence-layer/ #: ../../library/pickle.rst:168 msgid "" "Serialization is a more primitive notion than persistence; although :mod:" @@ -354,7 +363,7 @@ msgid "" "de-serialization, you can create a :class:`Pickler` or an :class:`Unpickler` " "object, respectively." msgstr "" -"想要序列化一個物件，你只需要呼叫 :func:`dumps` 函數。而當你想要去序列化一個資" +"想要序列化一個物件，你只需要呼叫 :func:`dumps` 函式。而當你想要去序列化一個資" "料流時，你只需要呼叫 :func:`loads` 即可。不過，若你希望能各自對序列化和去序列" "化的過程中有更多的掌控度，你可以自訂一個 :class:`Pickler` 或 :class:" "`Unpickler` 物件。" @@ -370,7 +379,7 @@ msgid "" "func:`dump` and :func:`dumps` as well as the :class:`Pickler` constructor." msgstr "" "一個整數，表示可使用的最高\\ :ref:`協定版本 `。這個值可作" -"為 *protocol* 的數值傳給 :func:`dump` 和 :func:`dumps` 函數以及 :class:" +"為 *protocol* 的數值傳給 :func:`dump` 和 :func:`dumps` 函式以及 :class:" "`Pickler` 建構式。" #: ../../library/pickle.rst:200 @@ -396,7 +405,7 @@ msgstr "預設協定版本為 4。" msgid "" "The :mod:`pickle` module provides the following functions to make the " "pickling process more convenient:" -msgstr ":mod:`pickle` 模組提供下列函數來簡化封裝的過程：" +msgstr ":mod:`pickle` 模組提供下列函式來簡化封裝的過程：" #: ../../library/pickle.rst:218 msgid "" @@ -567,7 +576,10 @@ msgstr "" "的新模組名稱轉換為 Python 2 所支援的舊名，以讓 Python 2 能正確地讀取此資料" "流。" -# SkyLull: 以下幾個關於 buffer_callback 的翻譯需要進一步的校對。何謂out-of-band? buffer view 應作何翻譯？ +# SkyLull: 以下幾個關於 buffer_callback 的翻譯需要進一步的校對。何謂out-of-band? buffer view +# 應作何翻譯？ +# out-of-band 目前參考 https://kb.synology.com/zh- +# tw/DSM/tutorial/Quick_Start_OOB_Management `帶外管理` 譯作 `帶外` #: ../../library/pickle.rst:317 msgid "" "If *buffer_callback* is ``None`` (the default), buffer views are serialized " @@ -583,8 +595,8 @@ msgid "" "``None``), the given buffer is :ref:`out-of-band `; otherwise " "the buffer is serialized in-band, i.e. inside the pickle stream." msgstr "" -"如果 *buffer_callback* 不是 ``None``，則它可以被多次呼叫並傳遞一個緩衝區的視" -"圖。如果回呼函數回傳一個假值（例如 ``None``），則所給的緩衝區將被視為 :ref:`" +"如果 *buffer_callback* 不是 ``None``，則它可以被多次呼叫並回傳一個緩衝區的視" +"圖。如果回呼函式回傳一個假值（例如 ``None``），則所給的緩衝區將被視為 :ref:`" "帶外資料 `；否則，該緩衝區將被視為 pickle 串流的帶內資料被序列" "化。" @@ -606,7 +618,7 @@ msgstr "將已封裝（pickled）的 *obj* 寫入已在建構式中開啟的對 msgid "Do nothing by default. This exists so a subclass can override it." msgstr "" "預設不進行任何動作。這是一種抽象方法，用於讓後續繼承這個類別的物件可以覆寫本" -"方法函數。" +"方法函式。" #: ../../library/pickle.rst:340 msgid "" @@ -625,6 +637,13 @@ msgstr "" msgid "See :ref:`pickle-persistent` for details and examples of uses." msgstr "關於細節與用法範例請見 :ref:`pickle-persistent`。" +# SkyLull: [t] +# dispatch table -> 調度表 +# https://zh.wiktionary.org/zh-hant/dispatch_table +# reduce -> 縮減 +# reduction function -> 縮減函式 +# 這個是指reduce()函式類型的運算，類似sql的aggregation類型運算，故參閱以下內文，譯為縮減 +# https://support.google.com/docs/answer/12657238?hl=zh-Hant #: ../../library/pickle.rst:350 msgid "" "A pickler object's dispatch table is a registry of *reduction functions* of " @@ -633,6 +652,10 @@ msgid "" "reduction function takes a single argument of the associated class and " "should conform to the same interface as a :meth:`~object.__reduce__` method." msgstr "" +"封裝器（pickler）物件含有的的調度表是一個 *縮減函式* （reduction function）的" +"註冊表，可以使用 :func:`copyreg.pickle` 來宣告這類縮減函式。它是一個以類別為" +"鍵、還原函式為值的映射表。縮減函式應準備接收一個對應類別的引數，並應遵循與 :" +"meth:`~object.__reduce__` 方法相同的介面。" #: ../../library/pickle.rst:358 msgid "" @@ -644,6 +667,11 @@ msgid "" "`dispatch_table` attribute then this will be used as the default dispatch " "table for instances of that class." msgstr "" +"預設情況下，封裝器（pickler）物件不會有 :attr:`dispatch_table` 屬性，而是會使" +"用由 :mod:`copyreg` 模組管理的全域調度表。不過，若要自訂某個封裝器（pickler）" +"物件的序列化行為，可以將 :attr:`dispatch_table` 屬性設置為類字典物件。另外，" +"如果 :class:`Pickler` 的子類別具有 :attr:`dispatch_table` 屬性，那麼這個屬性" +"將作為該子類別實例的預設調度表。" #: ../../library/pickle.rst:367 msgid "See :ref:`pickle-dispatch` for usage examples." @@ -657,10 +685,12 @@ msgid "" "and can optionally return :data:`NotImplemented` to fallback on :attr:" "`dispatch_table`-registered reducers to pickle ``obj``." msgstr "" +"傳 :data:`NotImplemented` 以退回（fallback）並改為使用 :attr:" +"`dispatch_table` 中登錄的縮減方法來封裝 ``obj``。" #: ../../library/pickle.rst:379 msgid "For a detailed example, see :ref:`reducer_override`." -msgstr "" +msgstr "請查閱 :ref:`reducer_override` 來參考其他較詳細的範例。" #: ../../library/pickle.rst:385 msgid "" @@ -669,20 +699,23 @@ msgid "" "superfluous PUT opcodes. It should not be used with self-referential " "objects, doing otherwise will cause :class:`Pickler` to recurse infinitely." msgstr "" +"已棄用。如果設置為 true，將啟用快速模式。快速模式會停用備忘（memo），因此能透" +"過不產生多餘的 PUT 操作碼（OpCode）來加速封裝過程。它不應被用於自我參照物件，" +"否則將導致 :class:`Pickler` 陷入無限遞迴。" #: ../../library/pickle.rst:391 msgid "Use :func:`pickletools.optimize` if you need more compact pickles." -msgstr "" +msgstr "使用 :func:`pickletools.optimize` 以獲得更緊湊的 pickle 輸出。" #: ../../library/pickle.rst:396 msgid "This takes a binary file for reading a pickle data stream." -msgstr "" +msgstr "這個物件接受一個二進位檔案 *file* 來從中讀取 pickle 資料流。" #: ../../library/pickle.rst:398 msgid "" "The protocol version of the pickle is detected automatically, so no protocol " "argument is needed." -msgstr "" +msgstr "協定版本號會被自動偵測，所以不需要在這邊手動輸入。" #: ../../library/pickle.rst:401 msgid "" @@ -693,6 +726,10 @@ msgid "" "binary reading, an :class:`io.BytesIO` object, or any other custom object " "that meets this interface." msgstr "" +"參數 *file* 必須擁有三個方法，分別是接受整數作為引數的 read() 方法、接受緩衝" +"區作為引數的 readinto() 方法以及不需要引數的 readline() 方法，如同在 :class:" +"`io.BufferedIOBase` 的介面一樣。因此，*file* 可以是一個以二進位讀取模式開啟的" +"檔案、一個 :class:`io.BytesIO` 物件、或任何符合此介面的自訂物件。" #: ../../library/pickle.rst:408 msgid "" @@ -707,6 +744,14 @@ msgid "" "datetime`, :class:`~datetime.date` and :class:`~datetime.time` pickled by " "Python 2." msgstr "" +"可選引數 *fix_imports*，*encoding* 和 *errors* 用來控制 Python 2 pickle 資料" +"的相容性支援。如果 *fix_imports* 為 true，則 pickle 模組會嘗試將舊的 Python " +"2 模組名稱映射到 Python 3 中使用的新名稱。*encoding* 和 *errors* 告訴 pickle " +"模組如何解碼由 Python 2 pickle 封裝的 8 位元字串實例；*encoding* 和 *errors* " +"預設分別為 'ASCII' 和 'strict'。*encoding* 可以設定為 'bytes' 以將這些 8 位元" +"字串實例讀為位元組物件。而由 Python 2 封裝的 NumPy 陣列、:class:`~datetime." +"datetime`、:class:`~datetime.date` 和 :class:`~datetime.time` 的實例則必須使" +"用 ``encoding='latin1'`` 來拆封。" #: ../../library/pickle.rst:419 msgid "" @@ -715,6 +760,9 @@ msgid "" "*buffer_callback* argument was ``None`` when a :class:`Pickler` was " "instantiated (or when :func:`dump` or :func:`dumps` was called)." msgstr "" +"如果 *buffers* 是 ``None``（預設值），那麼去序列化所需的所有資料都必須已經包" +"含在 pickle 串流中。這意味著當初在建立對應的 :class:`Pickler` 時（或在呼叫 :" +"func:`dump` 或 :func:`dumps` 時）*buffer_callback* 引數必須為 ``None``。" #: ../../library/pickle.rst:424 msgid "" @@ -723,6 +771,10 @@ msgid "" "of-band ` buffer view. Such buffers have been given in order to " "the *buffer_callback* of a Pickler object." msgstr "" +"如果 *buffers* 不是 ``None``，則其應該是一個可疊代物件，內含數個支援緩衝區的" +"物件，並且每當 pickle 串流引用一個 :ref:`帶外 ` 緩衝區視圖時將會" +"被照順序消耗。這些緩衝資料當初建立時應已按照順序給定予 Pickler 物件中的 " +"*buffer_callback*。" #: ../../library/pickle.rst:434 msgid "" From 853b0957f517a7d2667c6812a4d317a9abbd9a6c Mon Sep 17 00:00:00 2001 From: "Raynor@GullU" Date: Fri, 30 Aug 2024 06:37:31 +0800 Subject: [PATCH 08/17] docs(library/pickle.po): editing, up to line 994 --- library/pickle.po | 70 +++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 61 insertions(+), 9 deletions(-) diff --git a/library/pickle.po b/library/pickle.po index 102d770848..ba3da23a4f 100644 --- a/library/pickle.po +++ b/library/pickle.po @@ -782,10 +782,12 @@ msgid "" "in the constructor, and return the reconstituted object hierarchy specified " "therein. Bytes past the pickled representation of the object are ignored." msgstr "" +"開啟先前被傳入建構子的檔案，從中讀取一個被 pickle 封裝的物件，並回傳重建完成" +"的物件階層。超過 pickle 表示範圍的位元組會被忽略。" #: ../../library/pickle.rst:441 msgid "Raise an :exc:`UnpicklingError` by default." -msgstr "" +msgstr "預設會拋出 :exc:`UnpicklingError` 例外。" #: ../../library/pickle.rst:443 msgid "" @@ -793,6 +795,8 @@ msgid "" "the persistent ID *pid*. If an invalid persistent ID is encountered, an :" "exc:`UnpicklingError` should be raised." msgstr "" +"若有定義 :meth:`persistent_load`，則其將回傳符合持久化識別碼 `pid` 的物件。如" +"果遭遇了無效的持久化識別碼，則會引發 :exc:`UnpicklingError`。" #: ../../library/pickle.rst:451 msgid "" @@ -801,6 +805,9 @@ msgid "" "unlike its name suggests, :meth:`find_class` is also used for finding " "functions." msgstr "" +"如有需要將引入 *module* ，並從中返回名為 *name* 的物件，這裡的 *module* 和 " +"*name* 引數接受的輸入是 :class:`str` 物件。注意，雖然名稱上看起來不像，但 :" +"meth:`find_class` 亦可被用於尋找其他函式。" #: ../../library/pickle.rst:456 msgid "" @@ -808,6 +815,8 @@ msgid "" "how they can be loaded, potentially reducing security risks. Refer to :ref:" "`pickle-restrict` for details." msgstr "" +"子類別可以覆寫此方法以控制可以載入哪些類型的物件、以及如何載入它們，從而潛在" +"地降低安全性風險。詳情請參考 :ref:`pickle-restrict`。" #: ../../library/pickle.rst:460 msgid "" @@ -817,12 +826,18 @@ msgstr "" "引發一個附帶引數 ``module``、``name`` 的\\ :ref:`稽核事件 ` " "``pickle.find_class``。" +# SkyLull: [T] +# 參見 ＃729 +# wrapper -> 包裝器 #: ../../library/pickle.rst:464 msgid "" "A wrapper for a buffer representing picklable data. *buffer* must be a :ref:" "`buffer-providing ` object, such as a :term:`bytes-like " "object` or a N-dimensional array." msgstr "" +"一個表示了含有可封裝數據緩衝區的包裝函數（wrapper function）。*buffer* 必須是" +"一個 :ref:`提供緩衝區 ` 的物件，例如一個 :term:`類位元組物件" +"（bytes-like object）` 或 N 維陣列。" #: ../../library/pickle.rst:468 msgid "" @@ -830,6 +845,8 @@ msgid "" "to pass it to other APIs expecting a buffer-providing object, such as :class:" "`memoryview`." msgstr "" +":class:`PickleBuffer` 本身就是一個提供緩衝區的物件，所以是能夠將其提供給其它" +"「預期收到含有緩衝物件的 API」的，比如 :class:`memoryview`。" #: ../../library/pickle.rst:472 msgid "" @@ -837,7 +854,12 @@ msgid "" "or higher. They are eligible for :ref:`out-of-band serialization `." msgstr "" +":class:`PickleBuffer` 物件僅能由 5 版或以上的 pickle 協定進行封裝。該物件亦能" +"被作為帶外資料來進行:ref:`帶外資料序列化 `" +# SkyLull: [T] oh boy... 好多術語... +# format B: https://learn.microsoft.com/zh-tw/dotnet/standard/base-types/standard-numeric-format-strings#BFormatString +# C-contiguous, Fortran-contiguous: https://stackoverflow.com/a/26999092 #: ../../library/pickle.rst:480 msgid "" "Return a :class:`memoryview` of the memory area underlying this buffer. The " @@ -845,53 +867,63 @@ msgid "" "``B`` (unsigned bytes). :exc:`BufferError` is raised if the buffer is " "neither C- nor Fortran-contiguous." msgstr "" +"返回此緩衝區底層記憶體區域的 :class:`memoryview`。被返回的物件是一個（在 C 語" +"言的 formatter 格式中）以 ``B`` (unsigned bytes) 二進位格式儲存、一維且列連續" +"（C-contiguous）的 memoryview。如果緩衝區既不是列連續（C-contiguous）也不是行" +"連續（Fortran-contiguous）的，則會引發 :exc:`BufferError`。" #: ../../library/pickle.rst:487 msgid "Release the underlying buffer exposed by the PickleBuffer object." -msgstr "" +msgstr "釋放 PickleBuffer 物件現正曝光中的緩衝區。" #: ../../library/pickle.rst:493 msgid "What can be pickled and unpickled?" -msgstr "" +msgstr "哪些物件能或不能被封裝、拆封？" #: ../../library/pickle.rst:495 msgid "The following types can be pickled:" -msgstr "" +msgstr "下列型別可以被封裝：" #: ../../library/pickle.rst:497 msgid "" "built-in constants (``None``, ``True``, ``False``, ``Ellipsis``, and :data:" "`NotImplemented`);" msgstr "" +"內建常數（``None``、``True``、``False``、``Ellipsis`` 和 :data:" +"`NotImplemented`）；" #: ../../library/pickle.rst:500 msgid "integers, floating-point numbers, complex numbers;" -msgstr "" +msgstr "整數、浮點數和複數；" #: ../../library/pickle.rst:502 msgid "strings, bytes, bytearrays;" -msgstr "" +msgstr "字串、位元組物件、位元組陣列；" #: ../../library/pickle.rst:504 msgid "" "tuples, lists, sets, and dictionaries containing only picklable objects;" -msgstr "" +msgstr "元組（tuple）、串列（list）、集合（set）和僅含有可封裝物件的字典；" #: ../../library/pickle.rst:506 msgid "" "functions (built-in and user-defined) accessible from the top level of a " "module (using :keyword:`def`, not :keyword:`lambda`);" msgstr "" +"在模組最表面的層級就能被存取的函式（內建或自訂的皆可，不過僅限使用 :keyword:" +"`def` 定義的函式，:keyword:`lambda` 函式不適用）；" #: ../../library/pickle.rst:509 msgid "classes accessible from the top level of a module;" -msgstr "" +msgstr "在模組最表面的層級就能被存取的類別；" #: ../../library/pickle.rst:511 msgid "" "instances of such classes whose the result of calling :meth:`~object." "__getstate__` is picklable (see section :ref:`pickle-inst` for details)." msgstr "" +"實例，只要在呼叫了 :meth:`~object.__getstate__` 後其回傳值全都是可封裝物件。" +"（詳情請參閱 :ref:`pickle-inst`）。" #: ../../library/pickle.rst:514 msgid "" @@ -902,7 +934,14 @@ msgid "" "`RecursionError` will be raised in this case. You can carefully raise this " "limit with :func:`sys.setrecursionlimit`." msgstr "" +"嘗試封裝無法封裝的物件會引發 :exc:`PicklingError` 例外；注意當這種情況發生" +"時，可能已經有未知數量的位元組已被寫入到檔案。嘗試封裝深度遞迴的資料結構可能" +"會導致其超出最大遞迴深度，在這種情況下會引發 :exc:`RecursionError` 例外。你可" +"以（小心地）使用 :func:`sys.setrecursionlimit` 來提高此上限。" +# SkyLull: [T] +# 請見官方術語表 +# qualified name -> 限定名稱 #: ../../library/pickle.rst:521 msgid "" "Note that functions (built-in and user-defined) are pickled by fully :term:" @@ -913,6 +952,11 @@ msgid "" "environment, and the module must contain the named object, otherwise an " "exception will be raised. [#]_" msgstr "" +"請注意，函式（內建及自訂兩者皆是）是依據完整的 :term:`限定名稱 ` 來封裝，而非依其值。[#]_ 這意味著封裝時只有函式名稱、所屬的模組和所屬" +"的類別名稱會被封裝。函式本身的程式碼及其附帶的任何屬性均不會被封裝。因此，在" +"拆封該物件的環境中，定義此函式的模組必須可被引入，且該模組必須包含具此命名之" +"物件，否則將引發例外。 [#]_" #: ../../library/pickle.rst:528 msgid "" @@ -921,12 +965,15 @@ msgid "" "class's code or data is pickled, so in the following example the class " "attribute ``attr`` is not restored in the unpickling environment::" msgstr "" +"同樣情況，類別是依照其完整限定名稱來進行封裝，因此在進行拆封的環境中會具有同" +"上的限制。類別中的程式碼或資料皆不會被封裝，因此在以下範例中，注意到類別屬性 " +"``attr`` 在拆封的環境中不會被還原::" #: ../../library/pickle.rst:538 msgid "" "These restrictions are why picklable functions and classes must be defined " "at the top level of a module." -msgstr "" +msgstr "這些限制就是可封裝的函式和類別必須被定義在模組頂層的原因。" #: ../../library/pickle.rst:541 msgid "" @@ -939,6 +986,11 @@ msgid "" "that suitable conversions can be made by the class's :meth:`~object." "__setstate__` method." msgstr "" +"同樣地，當類別實例被封裝時，它所屬類別具有的程式碼和資料不會被一起封裝。只有" +"實例資料本身會被封裝。這是有意而為的，因為如此你才可以在類別中修正錯誤或新增" +"其他方法，且於此同時仍能夠載入使用較早期版本的類別所建立的物件實例。如果您預" +"計將有長期存在的物件、且該物件將經歷許多版本的更替，你可以在物件中存放一個版" +"本號，以便未來能透過 :meth:`~object.__setstate__` 方法來進行適當的版本轉換。" #: ../../library/pickle.rst:553 msgid "Pickling Class Instances" From 148a7546bfa4c55b7d66bbbf87aa2f947b967f8f Mon Sep 17 00:00:00 2001 From: "Raynor@GullU" Date: Fri, 6 Sep 2024 17:34:01 +0800 Subject: [PATCH 09/17] docs(library/pickle.po): editing, up to line 1178 --- library/pickle.po | 63 ++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 54 insertions(+), 9 deletions(-) diff --git a/library/pickle.po b/library/pickle.po index 22467f56d4..360d337efa 100644 --- a/library/pickle.po +++ b/library/pickle.po @@ -96,7 +96,7 @@ msgid "" "pyc` files." msgstr "" "Python 有另一個比較原始的序列化模組叫 :mod:`marshal`，不過其設計目的是為了支" -"援 Python 的預編譯功能 :file:`.pyc` 運作。總地來說，沒事不要用 :mod:" +"援 Python 的預編譯功能 :file:`.pyc` 的運作。總地來說，沒事不要用 :mod:" "`marshal`。" #: ../../library/pickle.rst:57 @@ -194,7 +194,7 @@ msgstr "" "JSON 具有高互通性（interoperability）且在 Python 以外的環境也被大量利用，但 " "pickle 只能在 Python 內使用。" -# Skylull: [t] +# Skylull: [T] # introspection -> 自省 # introspection facilities -> 自省措施 # https://zh.wikipedia.org/wiki/%E5%86%85%E7%9C%81_(%E8%AE%A1%E7%AE%97%E6%9C%BA%E7%A7%91%E5%AD%A6) @@ -323,7 +323,7 @@ msgstr "" "版本 5 的協定在 Python 3.8 被新增。現在能支援帶外資料（Out-of-band data）並加" "速帶內資料的處理速度。請參閱 :pep:`574` 以了解第 5 版協定改進的細節。" -# SkyLull: [t] +# SkyLull: [T] # persistent -> 持久 # data persistent -> 資料持久化 # https://zh.wikipedia.org/zh- @@ -637,7 +637,7 @@ msgstr "" msgid "See :ref:`pickle-persistent` for details and examples of uses." msgstr "關於細節與用法範例請見 :ref:`pickle-persistent`。" -# SkyLull: [t] +# SkyLull: [T] # dispatch table -> 調度表 # https://zh.wiktionary.org/zh-hant/dispatch_table # reduce -> 縮減 @@ -857,8 +857,9 @@ msgstr "" ":class:`PickleBuffer` 物件僅能由 5 版或以上的 pickle 協定進行封裝。該物件亦能" "被作為帶外資料來進行:ref:`帶外資料序列化 `" -# SkyLull: [T] oh boy... 好多術語... -# format B: https://learn.microsoft.com/zh-tw/dotnet/standard/base-types/standard-numeric-format-strings#BFormatString +# SkyLull: oh boy... 好多術語... +# format B: https://learn.microsoft.com/zh-tw/dotnet/standard/base- +# types/standard-numeric-format-strings#BFormatString # C-contiguous, Fortran-contiguous: https://stackoverflow.com/a/26999092 #: ../../library/pickle.rst:480 msgid "" @@ -994,13 +995,15 @@ msgstr "" #: ../../library/pickle.rst:553 msgid "Pickling Class Instances" -msgstr "" +msgstr "Pickling 類別實例" #: ../../library/pickle.rst:557 msgid "" "In this section, we describe the general mechanisms available to you to " "define, customize, and control how class instances are pickled and unpickled." msgstr "" +"在這一個章節，我們會講述如何封裝或拆封一個物件實例的相關機制，以方便你進行自" +"訂。" #: ../../library/pickle.rst:560 msgid "" @@ -1011,12 +1014,17 @@ msgid "" "creates an uninitialized instance and then restores the saved attributes. " "The following code shows an implementation of this behaviour::" msgstr "" +"大部分的實例不需要額外的程式碼就已經是可封裝的了。在這樣的預設狀況中，pickle " +"模組透過自省機制來取得類別及其實例的屬性。當類別實例被拆封時，其 :meth:" +"`~object.__init__` 方法通常*不會*被呼叫。預設行為首先會建立一個未初始化的實" +"例，然後還原紀錄中的屬性。以下程式碼的實作展示了前述行為::" #: ../../library/pickle.rst:575 msgid "" "Classes can alter the default behaviour by providing one or several special " "methods:" msgstr "" +"被封裝的目標類別可以提供一個或數個下列特殊方法來改變 pickle 的預設行為：" #: ../../library/pickle.rst:580 msgid "" @@ -1027,6 +1035,10 @@ msgid "" "dictionary of named arguments for constructing the object. Those will be " "passed to the :meth:`__new__` method upon unpickling." msgstr "" +"在第 2 版協定或更新的版本中，有實作 :meth:`__getnewargs_ex__` 方法的類別，可" +"以決定在拆封時要傳遞給 :meth:`__new__` 方法的值。該方法必須回傳一個 ``(args, " +"kwargs)`` 的組合，其中 *args* 是一個位置引數的元組（tuple），*kwargs* 是一個" +"用於建構物件的命名引數字典。這些資訊將在拆封時傳遞給 :meth:`__new__` 方法。" #: ../../library/pickle.rst:588 msgid "" @@ -1034,10 +1046,12 @@ msgid "" "requires keyword-only arguments. Otherwise, it is recommended for " "compatibility to implement :meth:`__getnewargs__`." msgstr "" +"如果目標類別的方法 :meth:`__new__` 需要僅限關鍵字的參數時，你應該實作此方法。" +"否則，為了提高相容性，建議你改為實作 :meth:`__getnewargs__`。" #: ../../library/pickle.rst:592 msgid ":meth:`__getnewargs_ex__` is now used in protocols 2 and 3." -msgstr "" +msgstr "在第 2、3 版的協定中現在改為使用 :meth:`__getnewargs_ex__`。" #: ../../library/pickle.rst:598 msgid "" @@ -1045,18 +1059,24 @@ msgid "" "supports only positional arguments. It must return a tuple of arguments " "``args`` which will be passed to the :meth:`__new__` method upon unpickling." msgstr "" +"此方法與 :meth:`__getnewargs_ex__` 的目的一樣，但僅支援位置參數。它必須回傳一" +"個由傳入引數所組成的元組（tuple）``args``，這些引數會在拆封時傳遞給 :meth:" +"`__new__` 方法。" #: ../../library/pickle.rst:602 msgid "" ":meth:`__getnewargs__` will not be called if :meth:`__getnewargs_ex__` is " "defined." msgstr "" +"當有定義 :meth:`__getnewargs_ex__` 的時候便不會呼叫 :meth:`__getnewargs__`。" #: ../../library/pickle.rst:605 msgid "" "Before Python 3.6, :meth:`__getnewargs__` was called instead of :meth:" "`__getnewargs_ex__` in protocols 2 and 3." msgstr "" +"在 Python 3.6 之前、版本 2 和版本 3 的協定中，會呼叫 :meth:`__getnewargs__` " +"而非 :meth:`__getnewargs_ex__`。" #: ../../library/pickle.rst:612 msgid "" @@ -1065,18 +1085,25 @@ msgid "" "pickled as the contents for the instance, instead of a default state. There " "are several cases:" msgstr "" +"目標類別可以透過覆寫方法 :meth:`__getstate__` 進一步影響其實例被封裝的方式。" +"封裝時，呼叫該方法所返回的物件將作為該實例的內容被封裝、而非一個預設狀態。以" +"下列出幾種預設狀態：" #: ../../library/pickle.rst:617 msgid "" "For a class that has no instance :attr:`~object.__dict__` and no :attr:" "`~object.__slots__`, the default state is ``None``." msgstr "" +"沒有 :attr:`~object.__dict__` 和 :attr:`~object.__slots__` 實例的類別，其預設" +"狀態為 ``None``。" #: ../../library/pickle.rst:620 msgid "" "For a class that has an instance :attr:`~object.__dict__` and no :attr:" "`~object.__slots__`, the default state is ``self.__dict__``." msgstr "" +"有 :attr:`~object.__dict__` 實例、但沒有 :attr:`~object.__slots__` 實例的類" +"別，其預設狀態為 ``self.__dict__``。" #: ../../library/pickle.rst:623 msgid "" @@ -1085,6 +1112,10 @@ msgid "" "``self.__dict__``, and a dictionary mapping slot names to slot values. Only " "slots that have a value are included in the latter." msgstr "" +"有 :attr:`~object.__dict__` 和 :attr:`~object.__slots__` 實例的類別，其預設狀" +"態是一個含有兩個字典的元組（tuple），該二字典分別為 ``self.__dict__`` 本身，" +"和紀錄欄位（slot）名稱和值對應關係的字典（只有含有值的欄位（slot）會被紀錄其" +"中）。" #: ../../library/pickle.rst:629 msgid "" @@ -1093,12 +1124,15 @@ msgid "" "``None`` and whose second item is a dictionary mapping slot names to slot " "values described in the previous bullet." msgstr "" +"沒有 :attr:`~object.__dict__` 但有 :attr:`~object.__slots__` 實例的類別，其預" +"設狀態是一個二元組（tuple），元組中的第一個值是 ``None``，第二個值則是紀錄欄" +"位（slot）名稱和值對應關係的字典（與前一項提到的字典是同一個）。" #: ../../library/pickle.rst:634 msgid "" "Added the default implementation of the ``__getstate__()`` method in the :" "class:`object` class." -msgstr "" +msgstr "在 :class:`object` 類別中增加預設的 ``__getstate__()`` 實作。" #: ../../library/pickle.rst:641 msgid "" @@ -1107,12 +1141,17 @@ msgid "" "state object to be a dictionary. Otherwise, the pickled state must be a " "dictionary and its items are assigned to the new instance's dictionary." msgstr "" +"在拆封時，如果類別定義了 :meth:`__setstate__`，則會使用拆封後的狀態呼叫它。在" +"這種情況下，紀錄狀態的物件不需要是字典（dictionary）。否則，封裝時的狀態紀錄" +"必須是一個字典，其紀錄的項目將被賦值給新實例的字典。" #: ../../library/pickle.rst:648 msgid "" "If :meth:`__reduce__` returns a state with value ``None`` at pickling, the :" "meth:`__setstate__` method will not be called upon unpickling." msgstr "" +"如果 :meth:`__reduce__` 在封裝時返回了 ``None`` 狀態，則拆封時就不會去呼叫 :" +"meth:`__setstate__`。" #: ../../library/pickle.rst:652 msgid "" @@ -1120,6 +1159,8 @@ msgid "" "use the methods :meth:`~object.__getstate__` and :meth:`~object." "__setstate__`." msgstr "" +"參閱 :ref:`pickle-state` 以了解 :meth:`~object.__getstate__` 和 :meth:" +"`~object.__setstate__` 的使用方法。" #: ../../library/pickle.rst:657 msgid "" @@ -1130,6 +1171,10 @@ msgid "" "such an invariant, as :meth:`~object.__init__` is not called when unpickling " "an instance." msgstr "" +"在拆封時，某些方法如 :meth:`~object.__getattr__`、:meth:`~object." +"__getattribute__` 或 :meth:`~object.__setattr__` 可能會在建立實例時被呼叫。如" +"果這些方法依賴了某些實例內部的不變性，則應實作 :meth:`~object.__new__` 以建立" +"此不變性，因為在拆封實例時不會呼叫 :meth:`~object.__init__`。" #: ../../library/pickle.rst:666 msgid "" From 080d0aad713ac4fe79d54a193ee6c347d6b63bed Mon Sep 17 00:00:00 2001 From: "Raynor@GullU" Date: Fri, 13 Sep 2024 20:19:13 +0800 Subject: [PATCH 10/17] docs(library/pickle.po): editing, up to line 1288 --- library/pickle.po | 31 ++++++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/library/pickle.po b/library/pickle.po index 360d337efa..e11ae8cc2f 100644 --- a/library/pickle.po +++ b/library/pickle.po @@ -1184,6 +1184,9 @@ msgid "" "unified interface for retrieving the data necessary for pickling and copying " "objects. [#]_" msgstr "" +"如稍後所演示，pickle 並不直接使用上述方法。這些方法實際上是實作了 :meth:" +"`~object.__reduce__` 特殊方法的拷貝協定（copy protocol）。拷貝協定提供了統一" +"的介面，以檢索進行封裝及複製物件時所需的資料。 [#]_" #: ../../library/pickle.rst:672 msgid "" @@ -1194,6 +1197,11 @@ msgid "" "We will show, however, cases where using :meth:`!__reduce__` is the only " "option or leads to more efficient pickling or both." msgstr "" +"直接在類別中實作 :meth:`~object.__reduce__` 雖然功能強大但卻容易導致出錯。因" +"此，設計類別者應盡可能使用高階介面（例如，:meth:`~object." +"__getnewargs_ex__`、:meth:`~object.__getstate__` 和 :meth:`~object." +"__setstate__`）。不過，我們也將展示一些特例狀況，在這些狀況中，使用 :meth:`!" +"__reduce__` 可能是唯一的選擇、是更有效率的封裝方法或二者兼備。" #: ../../library/pickle.rst:681 msgid "" @@ -1201,6 +1209,8 @@ msgid "" "method takes no argument and shall return either a string or preferably a " "tuple (the returned object is often referred to as the \"reduce value\")." msgstr "" +"目前的介面定義如下。 :meth:`__reduce__` 方法不接受引數，且應回傳一個字串或一" +"個元組（元組一般而言是較佳的選擇；所回傳的物件通常稱為「縮減值」）。" #: ../../library/pickle.rst:685 msgid "" @@ -1209,6 +1219,9 @@ msgid "" "module; the pickle module searches the module namespace to determine the " "object's module. This behaviour is typically useful for singletons." msgstr "" +"如果回傳的是字串，該字串應被解讀為一個全域變數的名稱。它應是該物件相對其所在" +"模組的本地名稱；pickle 模組會在模組命名空間中尋找，以確定該物件所在的模組。這" +"種行為通常對於單例物件特別有用。" #: ../../library/pickle.rst:690 msgid "" @@ -1216,18 +1229,22 @@ msgid "" "Optional items can either be omitted, or ``None`` can be provided as their " "value. The semantics of each item are in order:" msgstr "" +"當返回一個元組時，其長度必須介於兩至六項元素之間。可選項可以被省略，或者其值" +"可以被設為 ``None``。各項物件的語意依序為：" #: ../../library/pickle.rst:696 msgid "" "A callable object that will be called to create the initial version of the " "object." -msgstr "" +msgstr "一個將會被呼叫來創建初始版本物件的可呼叫物件。" #: ../../library/pickle.rst:699 msgid "" "A tuple of arguments for the callable object. An empty tuple must be given " "if the callable does not accept any argument." msgstr "" +"一個用於傳遞引數給前述物件的元組。如果前述物件不接受引數輸入，則你仍應在這裡" +"給定一個空元組。" #: ../../library/pickle.rst:702 msgid "" @@ -1236,6 +1253,9 @@ msgid "" "method then, the value must be a dictionary and it will be added to the " "object's :attr:`~object.__dict__` attribute." msgstr "" +"可選項。物件狀態。如前所述，會被傳遞給該物件的 :meth:`__setstate__` 方法。如" +"果該物件沒有實作此方法，則本值必須是一個字典，且其將會被新增到物件的 :attr:" +"`~object.__dict__` 屬性中。" #: ../../library/pickle.rst:707 msgid "" @@ -1248,6 +1268,12 @@ msgid "" "which pickle protocol version is used as well as the number of items to " "append, so both must be supported.)" msgstr "" +"可選項。一個用來提供連續項目的疊代器（而非序列）。這些項目將個別透過 ``obj." +"append(item)`` 方法或成批次地透過 ``obj.extend(list_of_items)`` 方法被附加到" +"物件中。主要用於串列（list）子類別，但只要其他類別具有相應的 :ref:`append 和 " +"extend 方法 `就也可以使用。 （如何選擇使用 :meth:`!append` " +"或 :meth:`!extend` 方法將取決於所選用的 pickle 協定版本以及要附加的項目數量，" +"因此必須同時支援這兩種方法。）" #: ../../library/pickle.rst:717 msgid "" @@ -1256,6 +1282,9 @@ msgid "" "value``. This is primarily used for dictionary subclasses, but may be used " "by other classes as long as they implement :meth:`__setitem__`." msgstr "" +"可選項。一個產生連續鍵值對的疊代器（不是序列）。這些項目將以 ``obj[key] = " +"value`` 方式被儲存到物件中。主要用於字典（dictionary）子類別，但只要有實現" +"了 :meth:`__setitem__` 的其他類別也可以使用。" #: ../../library/pickle.rst:722 msgid "" From 765ce6f5db9647666ab9eb41ba77887b39e22683 Mon Sep 17 00:00:00 2001 From: "Raynor@GullU" Date: Sun, 15 Sep 2024 21:12:33 +0800 Subject: [PATCH 11/17] docs(library/pickle.po): editing, up to line 1600 --- library/pickle.po | 124 +++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 118 insertions(+), 6 deletions(-) diff --git a/library/pickle.po b/library/pickle.po index 7e628ddd84..dc7fbff4e5 100644 --- a/library/pickle.po +++ b/library/pickle.po @@ -1287,6 +1287,9 @@ msgstr "" "果該物件沒有實作此方法，則本值必須是一個字典，且其將會被新增到物件的 :attr:" "`~object.__dict__` 屬性中。" +# SkyLull: [T] +# signature: https://stackoverflow.com/questions/72788932/what-is-a-function- +# signature -> 輸入特徵 #: ../../library/pickle.rst:707 msgid "" "Optionally, an iterator (and not a sequence) yielding successive items. " @@ -1301,9 +1304,9 @@ msgstr "" "可選項。一個用來提供連續項目的疊代器（而非序列）。這些項目將個別透過 ``obj." "append(item)`` 方法或成批次地透過 ``obj.extend(list_of_items)`` 方法被附加到" "物件中。主要用於串列（list）子類別，但只要其他類別具有相應的 :ref:`append 和 " -"extend 方法 `就也可以使用。 （如何選擇使用 :meth:`!append` " -"或 :meth:`!extend` 方法將取決於所選用的 pickle 協定版本以及要附加的項目數量，" -"因此必須同時支援這兩種方法。）" +"extend 方法 `和相同的輸入特徵（signature）就也可以使用。 " +"（如何選擇使用 :meth:`!append` 或 :meth:`!extend` 方法將取決於所選用的 " +"pickle 協定版本以及要附加的項目數量，因此必須同時支援這兩種方法。）" #: ../../library/pickle.rst:717 msgid "" @@ -1324,10 +1327,14 @@ msgid "" "method. If not ``None``, this callable will have priority over ``obj``'s :" "meth:`__setstate__`." msgstr "" +"可選項。一個具有 ``(obj, state)`` 輸入特徵（signature）的可呼叫物件。該物件允" +"許使用者以可編寫的邏輯，而不是物件 ``obj`` 預設的 :meth:`__setstate__` 靜態方" +"法去控制特定物件的狀態更新方式。如果這個物件不是 ``None``，這個物件的呼叫優先" +"權將優於物件 ``obj`` 的 :meth:`__setstate__`。" #: ../../library/pickle.rst:728 msgid "The optional sixth tuple item, ``(obj, state)``, was added." -msgstr "" +msgstr "加入第六個可選項（一個 ``(obj, state)`` 元組）。" #: ../../library/pickle.rst:734 msgid "" @@ -1338,10 +1345,14 @@ msgid "" "a synonym for the extended version. The main use for this method is to " "provide backwards-compatible reduce values for older Python releases." msgstr "" +"另外，你也可以定義一個 :meth:`__reduce_ex__` 方法。唯一的不同的地方是此方法只" +"接受協定版本（整數）作為參數。當有定義本方法時，pickle 會優先調用它而不是 :" +"meth:`__reduce__` 。此外，呼叫 :meth:`__reduce__` 時也會自動變成呼叫這個變體" +"版本。此方法主要是為了向後相容的舊的 Python 版本而存在。" #: ../../library/pickle.rst:746 msgid "Persistence of External Objects" -msgstr "" +msgstr "外部物件持久化" #: ../../library/pickle.rst:752 msgid "" @@ -1351,6 +1362,10 @@ msgid "" "of alphanumeric characters (for protocol 0) [#]_ or just an arbitrary object " "(for any newer protocol)." msgstr "" +"為了方便物件持久化，:mod:`pickle` 模組支援對被封裝資料串流以外的物件參照。被" +"參照的物件是透過一個持久化 ID 來參照的，這個 ID 應該要是字母數字字元" +"（alphanumeric）組成的字串（協定 0） [#]_ 或者是任意的物件（任何較新的協" +"定）。" #: ../../library/pickle.rst:758 msgid "" @@ -1359,6 +1374,9 @@ msgid "" "pickler and unpickler, :meth:`~Pickler.persistent_id` and :meth:`~Unpickler." "persistent_load` respectively." msgstr "" +":mod:`pickle` 沒有定義要如何解決或分派這個持久化 ID 的問題；故其處理方式有賴" +"使用者自行定義在封裝器（pickler）以及拆封器（unpickler）中。方法的名稱各自" +"為 :meth:`~Pickler.persistent_id` 和 :meth:`~Unpickler.persistent_load`。" #: ../../library/pickle.rst:763 msgid "" @@ -1370,6 +1388,11 @@ msgid "" "object, along with a marker so that the unpickler will recognize it as a " "persistent ID." msgstr "" +"要封裝具有外部持久化 ID 的物件，封裝器（pickler）必須擁有一個自訂的方法 :" +"meth:`~Pickler.persistent_id`，這個方法將接收一個物件作為參數，並回傳 `None` " +"或該物件的持久化 ID。當回傳 `None` 時，封裝器會正常地封裝該物件。當回傳一個持" +"久化 ID 字串時，封裝器會封裝該物件並加上一個標記，讓拆封器（unpikler）能識別" +"它是一個持久化 ID。" #: ../../library/pickle.rst:770 msgid "" @@ -1377,12 +1400,15 @@ msgid "" "`~Unpickler.persistent_load` method that takes a persistent ID object and " "returns the referenced object." msgstr "" +"要拆封外部物件，拆封器（unpickler）必須有一個自訂的 :meth:`~Unpickler." +"persistent_load` 方法，該方法應接受一個持久化 ID 物件，並回傳相對應的物件。" #: ../../library/pickle.rst:774 msgid "" "Here is a comprehensive example presenting how persistent ID can be used to " "pickle external objects by reference." msgstr "" +"以下是一個完整的範例，用以說明如何使用持久化 ID 來封裝具外部參照的物件。" #: ../../library/pickle.rst:777 msgid "" @@ -1481,10 +1507,96 @@ msgid "" "if __name__ == '__main__':\n" " main()\n" msgstr "" +"# 展示如何使用持久化 ID 來封裝外部物件的簡單範例\n" +"\n" +"import pickle\n" +"import sqlite3\n" +"from collections import namedtuple\n" +"\n" +"# 代表資料庫中紀錄的一個簡易類別\n" +"MemoRecord = namedtuple(\"MemoRecord\", \"key, task\")\n" +"\n" +"class DBPickler(pickle.Pickler):\n" +"\n" +" def persistent_id(self, obj):\n" +" # 我們派發出一個持久 ID，而不是像一般類別實例那樣封裝 MemoRecord。\n" +" if isinstance(obj, MemoRecord):\n" +" # 我們的持久 ID 就是一個元組，裡面包含一個標籤和一個鍵，指向資料" +"庫中的特定紀錄。\n" +" return (\"MemoRecord\", obj.key)\n" +" else:\n" +" # 如果 obj 沒有持久 ID，則返回 None。這表示 obj 像平常那樣封裝即" +"可。\n" +" return None\n" +"\n" +"\n" +"class DBUnpickler(pickle.Unpickler):\n" +"\n" +" def __init__(self, file, connection):\n" +" super().__init__(file)\n" +" self.connection = connection\n" +"\n" +" def persistent_load(self, pid):\n" +" # 每當遇到持久 ID 時，此方法都會被呼叫。\n" +" # pid 是 DBPickler 所回傳的元組。\n" +" cursor = self.connection.cursor()\n" +" type_tag, key_id = pid\n" +" if type_tag == \"MemoRecord\":\n" +" # 從資料庫中抓取所引用的紀錄並返回。\n" +" cursor.execute(\"SELECT * FROM memos WHERE key=?\", " +"(str(key_id),))\n" +" key, task = cursor.fetchone()\n" +" return MemoRecord(key, task)\n" +" else:\n" +" # 如果無法返回正確的物件，則必須拋出錯誤。\n" +" # 否則 unpickler 會誤認為 None 是持久 ID 所引用的物件。\n" +" raise pickle.UnpicklingError(\"unsupported persistent object\")\n" +"\n" +"\n" +"def main():\n" +" import io\n" +" import pprint\n" +"\n" +" # 初始化資料庫。\n" +" conn = sqlite3.connect(\":memory:\")\n" +" cursor = conn.cursor()\n" +" cursor.execute(\"CREATE TABLE memos(key INTEGER PRIMARY KEY, task " +"TEXT)\")\n" +" tasks = (\n" +" 'give food to fish',\n" +" 'prepare group meeting',\n" +" 'fight with a zebra',\n" +" )\n" +" for task in tasks:\n" +" cursor.execute(\"INSERT INTO memos VALUES(NULL, ?)\", (task,))\n" +"\n" +" # 抓取要封裝的紀錄。\n" +" cursor.execute(\"SELECT * FROM memos\")\n" +" memos = [MemoRecord(key, task) for key, task in cursor]\n" +" # 使用我們自訂的 DBPickler 來保存紀錄。\n" +" file = io.BytesIO()\n" +" DBPickler(file).dump(memos)\n" +"\n" +" print(\"被封裝的紀錄:\")\n" +" pprint.pprint(memos)\n" +"\n" +" # 更新一筆紀錄（測試用）。\n" +" cursor.execute(\"UPDATE memos SET task='learn italian' WHERE key=1\")\n" +"\n" +" # 從 pickle 資料流中載入紀錄。\n" +" file.seek(0)\n" +" memos = DBUnpickler(file, conn).load()\n" +"\n" +" print(\"已拆封的紀錄:\")\n" +" pprint.pprint(memos)\n" +"\n" +"\n" +"if __name__ == '__main__':\n" +" main()\n" #: ../../library/pickle.rst:782 msgid "Dispatch Tables" -msgstr "" +msgstr "分派表" #: ../../library/pickle.rst:784 msgid "" From 285a7ab31e88c7646348f12db4910bbae20769d5 Mon Sep 17 00:00:00 2001 From: "Raynor@GullU" Date: Thu, 19 Sep 2024 14:41:16 +0800 Subject: [PATCH 12/17] docs(library/pickle.po): editing, up to line 1982 --- library/pickle.po | 121 ++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 112 insertions(+), 9 deletions(-) diff --git a/library/pickle.po b/library/pickle.po index dc7fbff4e5..8d833b4006 100644 --- a/library/pickle.po +++ b/library/pickle.po @@ -1596,7 +1596,7 @@ msgstr "" #: ../../library/pickle.rst:782 msgid "Dispatch Tables" -msgstr "分派表" +msgstr "調度表" #: ../../library/pickle.rst:784 msgid "" @@ -1604,6 +1604,8 @@ msgid "" "other code which depends on pickling, then one can create a pickler with a " "private dispatch table." msgstr "" +"如果你希望在不干擾其他物件正常封裝的前提下建立一個針對特定物件的封裝器，你可" +"建立一個有私密調度表的封裝器。" #: ../../library/pickle.rst:788 msgid "" @@ -1611,6 +1613,9 @@ msgid "" "as :data:`!copyreg.dispatch_table`. Therefore, one may choose to use a " "modified copy of :data:`!copyreg.dispatch_table` as a private dispatch table." msgstr "" +"由 :mod:`copyreg` 模組管理的全域調度表可以 :data:`!copyreg.dispatch_table` 呼" +"叫。你可以透過這個方式來基於原始 :data:`!copyreg.dispatch_table` 創建一個修改" +"過的版本，作為你的專屬用途的調度表。" #: ../../library/pickle.rst:793 msgid "For example ::" @@ -1633,6 +1638,8 @@ msgid "" "creates an instance of :class:`pickle.Pickler` with a private dispatch table " "which handles the ``SomeClass`` class specially. Alternatively, the code ::" msgstr "" +"建立了一個 :class:`pickle.Pickler`，其中含有專門處裡 ``SomeClass`` 類別的專屬" +"調度表。此外，你也可以寫作：::" #: ../../library/pickle.rst:804 msgid "" @@ -1653,6 +1660,8 @@ msgid "" "does the same but all instances of ``MyPickler`` will by default share the " "private dispatch table. On the other hand, the code ::" msgstr "" +"這樣可產生相似的結果，唯一不同的是往後所有 ``MyPickler`` 預設都會使用這個專屬" +"調度表。最後，如果將程式寫為：::" #: ../../library/pickle.rst:813 msgid "" @@ -1668,11 +1677,11 @@ msgstr "" msgid "" "modifies the global dispatch table shared by all users of the :mod:`copyreg` " "module." -msgstr "" +msgstr "則會改變 :mod:`copyreg` 模組內建、所有使用者共通的調度表。" #: ../../library/pickle.rst:822 msgid "Handling Stateful Objects" -msgstr "" +msgstr "處裡紀錄大量狀態的物件" #: ../../library/pickle.rst:828 msgid "" @@ -1685,6 +1694,12 @@ msgid "" "__setstate__` and :meth:`!__getstate__` methods are used to implement this " "behavior. ::" msgstr "" +"以下的範例展示了如何修改針對特定類別封裝時的行為。下面的 :class:`!" +"TextReader` 類別會開啟一個文字檔案，並在每次呼叫其 :meth:`!readline` 方法時返" +"回當前行編號與該行內容。如果 :class:`!TextReader` 實例被封裝，所有*除了檔案物" +"件之外*的屬性成員都會被保存。在該實例被拆封時，檔案將被重新開啟，並從上次的位" +"置繼續讀取。這個行為的達成是透過 :meth:`!__setstate__` 和 :meth:`!" +"__getstate__` 方法來實作的。::" #: ../../library/pickle.rst:836 msgid "" @@ -1725,10 +1740,45 @@ msgid "" " # Finally, save the file.\n" " self.file = file" msgstr "" +"class TextReader:\n" +" \"\"\"列出文字檔案中的行並對其進行編號。\"\"\"\n" +"\n" +" def __init__(self, filename):\n" +" self.filename = filename\n" +" self.file = open(filename)\n" +" self.lineno = 0\n" +"\n" +" def readline(self):\n" +" self.lineno += 1\n" +" line = self.file.readline()\n" +" if not line:\n" +" return None\n" +" if line.endswith('\\n'):\n" +" line = line[:-1]\n" +" return \"%i: %s\" % (self.lineno, line)\n" +"\n" +" def __getstate__(self):\n" +" # 從 self.__dict__ 中複製物件的狀態。包含了所有的實例屬性。\n" +" # 使用 dict.copy() 方法以避免修改原始狀態。\n" +" state = self.__dict__.copy()\n" +" # 移除不可封裝的項目。\n" +" del state['file']\n" +" return state\n" +"\n" +" def __setstate__(self, state):\n" +" # 恢復實例屬性（即 filename 和 lineno）。\n" +" self.__dict__.update(state)\n" +" # 恢復到先前開啟了檔案的狀態。為此，我們需要重新開啟它並一直讀取到行" +"數編號相同。\n" +" file = open(self.filename)\n" +" for _ in range(self.lineno):\n" +" file.readline()\n" +" # 存檔。\n" +" self.file = file" #: ../../library/pickle.rst:874 msgid "A sample usage might be something like this::" -msgstr "" +msgstr "可以這樣實際使用：::" #: ../../library/pickle.rst:876 msgid "" @@ -1752,7 +1802,7 @@ msgstr "" #: ../../library/pickle.rst:888 msgid "Custom Reduction for Types, Functions, and Other Objects" -msgstr "" +msgstr "針對型別、函數或特定物件定製縮減函數" #: ../../library/pickle.rst:892 msgid "" @@ -1761,6 +1811,9 @@ msgid "" "the object's type, or we may want to customize the pickling of functions and " "classes." msgstr "" +"有時候，:attr:`~Pickler.dispatch_table` 的彈性空間可能不夠。尤其當我們想要使" +"用型別以外的方式來判斷如何使用自訂封裝、或者我們想要自訂特定函式和類別的封裝" +"方法時。" #: ../../library/pickle.rst:897 msgid "" @@ -1770,6 +1823,9 @@ msgid "" "alternatively return :data:`NotImplemented` to fallback to the traditional " "behavior." msgstr "" +"如果是這樣的話，可以繼承 :class:`Pickler` 類別並實作一個 :meth:`~Pickler." +"reducer_override` 方法。此方法可以回傳任意的縮減元組（參閱 :meth:`~object." +"__reduce__`）、也可以回傳 :data:`NotImplemented` 以回退至原始的行為。" #: ../../library/pickle.rst:902 msgid "" @@ -1777,6 +1833,8 @@ msgid "" "reducer_override` are defined, then :meth:`~Pickler.reducer_override` method " "takes priority." msgstr "" +"如果 :attr:`~Pickler.dispatch_table` 和 :meth:`~Pickler.reducer_override` 都" +"被定義了的話，:meth:`~Pickler.reducer_override` 的優先度較高。" #: ../../library/pickle.rst:907 msgid "" @@ -1786,12 +1844,16 @@ msgid "" "class:`dict`, :class:`set`, :class:`frozenset`, :class:`list` and :class:" "`tuple`." msgstr "" +"出於效能考量，處裡以下物件可能不會呼叫 :meth:`~Pickler.reducer_override`：" +"``None``、``True``、``False``，以及 :class:`int`、:class:`float`、:class:" +"`bytes`、:class:`str`、:class:`dict`、:class:`set`、:class:`frozenset`、:" +"class:`list` 和 :class:`tuple` 的實例。" #: ../../library/pickle.rst:913 msgid "" "Here is a simple example where we allow pickling and reconstructing a given " "class::" -msgstr "" +msgstr "以下是一個簡單的例子，我們示範如何允許封裝和重建給定的類別：::" #: ../../library/pickle.rst:916 msgid "" @@ -1823,10 +1885,37 @@ msgid "" "assert unpickled_class.__name__ == \"MyClass\"\n" "assert unpickled_class.my_attribute == 1" msgstr "" +"import io\n" +"import pickle\n" +"\n" +"class MyClass:\n" +" my_attribute = 1\n" +"\n" +"class MyPickler(pickle.Pickler):\n" +" def reducer_override(self, obj):\n" +" \"\"\"MyClass 的自訂縮減函數。\"\"\"\n" +" if getattr(obj, \"__name__\", None) == \"MyClass\":\n" +" return type, (obj.__name__, obj.__bases__,\n" +" {'my_attribute': obj.my_attribute})\n" +" else:\n" +" # 遭遇其他物件，則使用一般的縮減方式\n" +" return NotImplemented\n" +"\n" +"f = io.BytesIO()\n" +"p = MyPickler(f)\n" +"p.dump(MyClass)\n" +"\n" +"del MyClass\n" +"\n" +"unpickled_class = pickle.loads(f.getvalue())\n" +"\n" +"assert isinstance(unpickled_class, type)\n" +"assert unpickled_class.__name__ == \"MyClass\"\n" +"assert unpickled_class.my_attribute == 1\n" #: ../../library/pickle.rst:948 msgid "Out-of-band Buffers" -msgstr "" +msgstr "帶外（Out-of-band）資料緩衝區" #: ../../library/pickle.rst:952 msgid "" @@ -1837,6 +1926,10 @@ msgid "" "structure of objects into a sequential stream of bytes, intrinsically " "involves copying data to and from the pickle stream." msgstr "" +":mod:`pickle` 模組會被用於用於傳輸龐大的資料。此時，將複製記憶體的次數降到最" +"低以保持效能變得很重要。然而，:mod:`pickle` 模組的正常操作過程中，當它將物件" +"的圖狀結構（graph-like structure）轉換為連續的位元組串流時，本質上就涉及將資" +"料複製到封裝流以及從封裝流複製資料。" #: ../../library/pickle.rst:959 msgid "" @@ -1845,10 +1938,12 @@ msgid "" "implementation of the communications system) support the out-of-band " "transfer facilities provided by pickle protocol 5 and higher." msgstr "" +"如果*供給者*（被傳遞物件的型別的實作）與*消費者*（資訊交換系統的實作）都支援" +"由 pickle 協定 5 或更高版本提供的帶外傳輸功能，則可以避免此一先天限制。" #: ../../library/pickle.rst:965 msgid "Provider API" -msgstr "" +msgstr "供給者 API" #: ../../library/pickle.rst:967 msgid "" @@ -1857,6 +1952,9 @@ msgid "" "a :class:`PickleBuffer` instance (instead of e.g. a :class:`bytes` object) " "for any large data." msgstr "" +"要封裝的大型資料物件，則必須實作一個針對 5 版協定及以上的 :meth:`~object." +"__reduce_ex__` 方法，該方法應返回一個 :class:`PickleBuffer` 實例來處理任何大" +"型資料（而非返回如 :class:`bytes` 物件）。" #: ../../library/pickle.rst:972 msgid "" @@ -1866,16 +1964,21 @@ msgid "" "opt-in to tell :mod:`pickle` that they will handle those buffers by " "themselves." msgstr "" +"一個 :class:`PickleBuffer` 物件*指示*了當下底層的緩衝區狀態適合進行帶外資料傳" +"輸。這些物件仍然相容 :mod:`pickle` 模組的一般使用方式。消費者程式也可以選擇介" +"入，指示 :mod:`pickle` 他們將自行處理這些緩衝區。" #: ../../library/pickle.rst:979 msgid "Consumer API" -msgstr "" +msgstr "消費者 API" #: ../../library/pickle.rst:981 msgid "" "A communications system can enable custom handling of the :class:" "`PickleBuffer` objects generated when serializing an object graph." msgstr "" +"一個資訊交換系統可以決定要自行處裡序列化物件圖時產生的 :class:`PickleBuffer` " +"物件。" #: ../../library/pickle.rst:984 msgid "" From 67a53e58ed407b350920d466c862c148eca2160a Mon Sep 17 00:00:00 2001 From: "Raynor@GullU" Date: Mon, 30 Sep 2024 22:37:39 +0800 Subject: [PATCH 13/17] docs(library/pickle.po): First iteration of translation done --- library/pickle.po | 149 +++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 135 insertions(+), 14 deletions(-) diff --git a/library/pickle.po b/library/pickle.po index 8d833b4006..1f6b2b99c9 100644 --- a/library/pickle.po +++ b/library/pickle.po @@ -1988,6 +1988,10 @@ msgid "" "graph. Buffers accumulated by the *buffer_callback* will not see their data " "copied into the pickle stream, only a cheap marker will be inserted." msgstr "" +"傳送端需要傳遞一個調用緩衝區的回呼函數給 :class:`Pickler`（或 :func:`dump` " +"或 :func:`dumps` 函數）的 *buffer_callback* 引數，使每次生成 :class:" +"`PickleBuffer` 時，該物件在處理物件圖時能被呼叫。除了一個簡易標記以外，由 " +"*buffer_callback* 累積的緩衝區資料不會被複製到 pickle 串流中。" #: ../../library/pickle.rst:991 msgid "" @@ -1999,6 +2003,12 @@ msgid "" "reconstructors of the objects whose pickling produced the original :class:" "`PickleBuffer` objects." msgstr "" +"接收端需要傳遞一個緩衝區物件給 :class:`Unpickler`（或 :func:`load` 或 :func:" +"`loads` 函式）的 *buffers* 引數。該物件須是一個可疊代的（iterable）緩衝區" +"（buffer）物件，其中包含傳遞給 *buffer_callback* 的緩衝區物件。這個可疊代物件" +"的緩衝區順序應該與它們當初被封裝時傳遞給 *buffer_callback* 的順序相同。這些緩" +"衝區將提供物件重建所需的資料，以使重建器能還原出那個當時產生了 :class:" +"`PickleBuffer` 的物件。" #: ../../library/pickle.rst:999 msgid "" @@ -2007,6 +2017,8 @@ msgid "" "Potential optimizations include the use of shared memory or datatype-" "dependent compression." msgstr "" +"在傳送與接收端之間，通訊系統可以自由實作轉移帶外緩衝區資料的機制。該機制可能" +"可以利用共用記憶體機制或根據資料類型特定的壓縮方式來最佳化執行速度。" #: ../../library/pickle.rst:1005 msgid "Example" @@ -2017,6 +2029,8 @@ msgid "" "Here is a trivial example where we implement a :class:`bytearray` subclass " "able to participate in out-of-band buffer pickling::" msgstr "" +"這一個簡單的範例展示了如何實作一個可以參與帶外緩衝區封裝的 :class:" +"`bytearray` 子類別：::" #: ../../library/pickle.rst:1010 msgid "" @@ -2041,6 +2055,25 @@ msgid "" " else:\n" " return cls(obj)" msgstr "" +"class ZeroCopyByteArray(bytearray):\n" +"\n" +" def __reduce_ex__(self, protocol):\n" +" if protocol >= 5:\n" +" return type(self)._reconstruct, (PickleBuffer(self),), None\n" +" else:\n" +" # PickleBuffer 在 pickle 協定 <= 4 時禁止使用。\n" +" return type(self)._reconstruct, (bytearray(self),)\n" +"\n" +" @classmethod\n" +" def _reconstruct(cls, obj):\n" +" with memoryview(obj) as m:\n" +" # 取得對原始緩衝區物件的控制\n" +" obj = m.obj\n" +" if type(obj) is cls:\n" +" # 若原本的緩衝區物件是 ZeroCopyByteArray，則直接回傳。\n" +" return obj\n" +" else:\n" +" return cls(obj)" #: ../../library/pickle.rst:1031 msgid "" @@ -2048,12 +2081,16 @@ msgid "" "providing object if it has the right type. This is an easy way to simulate " "zero-copy behaviour on this toy example." msgstr "" +"如果型別正確，重建器（``_reconstruct`` 類別方法）會返回當時提供緩衝區的物件。" +"這個簡易實作可以模擬一個無複製行為的重建器。" #: ../../library/pickle.rst:1035 msgid "" "On the consumer side, we can pickle those objects the usual way, which when " "unserialized will give us a copy of the original object::" msgstr "" +"在使用端，我們可以用一般的方式封裝這些物件，當我們拆封時會得到一個原始物件的" +"副本：::" #: ../../library/pickle.rst:1038 msgid "" @@ -2063,12 +2100,19 @@ msgid "" "print(b == new_b) # True\n" "print(b is new_b) # False: a copy was made" msgstr "" +"b = ZeroCopyByteArray(b\"abc\")\n" +"data = pickle.dumps(b, protocol=5)\n" +"new_b = pickle.loads(data)\n" +"print(b == new_b) # True\n" +"print(b is new_b) # False: 曾進行過複製運算" #: ../../library/pickle.rst:1044 msgid "" "But if we pass a *buffer_callback* and then give back the accumulated " "buffers when unserializing, we are able to get back the original object::" msgstr "" +"但如果我們傳一個 *buffer_callback* 並在去序列化時正確返回積累的緩衝資料，我們" +"就能拿回原始的物件：::" #: ../../library/pickle.rst:1047 msgid "" @@ -2079,6 +2123,12 @@ msgid "" "print(b == new_b) # True\n" "print(b is new_b) # True: no copy was made" msgstr "" +"b = ZeroCopyByteArray(b\"abc\")\n" +"buffers = []\n" +"data = pickle.dumps(b, protocol=5, buffer_callback=buffers.append)\n" +"new_b = pickle.loads(data, buffers=buffers)\n" +"print(b == new_b) # True\n" +"print(b is new_b) # True: 沒有進行過複製" #: ../../library/pickle.rst:1054 msgid "" @@ -2089,14 +2139,18 @@ msgid "" "making as few copies as possible) when transferring between distinct " "processes or systems." msgstr "" +"此範例是因為受限於 :class:`bytearray` 會自行分配記憶體：您無法創建以其他物件" +"的記憶體為基礎的 :class:`bytearray` 實例。不過第三方資料型態（如 NumPy 陣列）" +"則可能沒有這個限制，而允許在不同程序或系統之間傳輸資料時使用零拷貝封裝（或儘" +"可能地減少拷貝次數）。" #: ../../library/pickle.rst:1061 msgid ":pep:`574` -- Pickle protocol 5 with out-of-band data" -msgstr "" +msgstr ":pep:`574` -- 第 5 版 Pickle 協定的帶外資料（out-of-band data）處裡" #: ../../library/pickle.rst:1067 msgid "Restricting Globals" -msgstr "" +msgstr "限制全域物件" #: ../../library/pickle.rst:1072 msgid "" @@ -2105,6 +2159,9 @@ msgid "" "it permits the unpickler to import and invoke arbitrary code. Just consider " "what this hand-crafted pickle data stream does when loaded::" msgstr "" +"預設情況下，拆封過程將會引入任何在 pickle 資料中找到的類別或函式。對於許多應" +"用程式來說，這種行為是不可接受的，因為它讓拆封器能夠引入並執行任意程式碼。請" +"參見以下 pickle 資料流在載入時的行為：::" #: ../../library/pickle.rst:1077 msgid "" @@ -2125,6 +2182,9 @@ msgid "" "is inoffensive, it is not difficult to imagine one that could damage your " "system." msgstr "" +"在這個例子中，拆封器會引入 :func:`os.system` 函式，然後執行命令「echo hello " +"world」。雖然這個例子是無害的，但不難想像可以這個方式輕易執行任意可能對系統造" +"成損害的命令。" #: ../../library/pickle.rst:1086 msgid "" @@ -2134,12 +2194,18 @@ msgid "" "requested. Thus it is possible to either completely forbid globals or " "restrict them to a safe subset." msgstr "" +"基於以上原因，您可能會希望透過自訂 :meth:`Unpickler.find_class` 來控制哪些是" +"能夠被拆封的內容。與其名稱字面意義暗示的不同，實際上每當你請求一個全域物件" +"（例如，類別或函式）時，就會調用 :meth:`Unpickler.find_class`。因此，可以透過" +"這個方法完全禁止全域物件或將其限制在安全的子集合。" #: ../../library/pickle.rst:1092 msgid "" "Here is an example of an unpickler allowing only few safe classes from the :" "mod:`builtins` module to be loaded::" msgstr "" +"以下是一個僅允許從 :mod:`builtins` 模組中載入少數安全類別的拆封器" +"（unpickler）的例子：::" #: ../../library/pickle.rst:1095 msgid "" @@ -2169,10 +2235,35 @@ msgid "" " \"\"\"Helper function analogous to pickle.loads().\"\"\"\n" " return RestrictedUnpickler(io.BytesIO(s)).load()" msgstr "" +"import builtins\n" +"import io\n" +"import pickle\n" +"\n" +"safe_builtins = {\n" +" 'range',\n" +" 'complex',\n" +" 'set',\n" +" 'frozenset',\n" +" 'slice',\n" +"}\n" +"\n" +"class RestrictedUnpickler(pickle.Unpickler):\n" +"\n" +" def find_class(self, module, name):\n" +" # 只允許幾個內建的安全類別\n" +" if module == \"builtins\" and name in safe_builtins:\n" +" return getattr(builtins, name)\n" +" # 完全禁止任何其他類別\n" +" raise pickle.UnpicklingError(\"global '%s.%s' is forbidden\" %\n" +" (module, name))\n" +"\n" +"def restricted_loads(s):\n" +" \"\"\"一個模擬 pickle.loads() 的輔助函數\"\"\"\n" +" return RestrictedUnpickler(io.BytesIO(s)).load()" #: ../../library/pickle.rst:1121 msgid "A sample usage of our unpickler working as intended::" -msgstr "" +msgstr "我們剛才實作的的拆封器範例正常運作的樣子：::" #: ../../library/pickle.rst:1123 msgid "" @@ -2209,10 +2300,13 @@ msgid "" "alternatives such as the marshalling API in :mod:`xmlrpc.client` or third-" "party solutions." msgstr "" +"正如我們的範例所示，必須謹慎審視能被拆封的內容。因此，如果您的應用場景非常關" +"心安全性，您可能需要考慮其他選擇，例如 :mod:`xmlrpc.client` 中的 marshalling " +"API 或其他第三方解決方案。" #: ../../library/pickle.rst:1147 msgid "Performance" -msgstr "" +msgstr "效能" #: ../../library/pickle.rst:1149 msgid "" @@ -2220,6 +2314,9 @@ msgid "" "efficient binary encodings for several common features and built-in types. " "Also, the :mod:`pickle` module has a transparent optimizer written in C." msgstr "" +"較近期的 pickle 協定版本（從 2 版協定開始）為多種常見功能和內建型別提供了高效" +"率的二進位編碼。此外，:mod:`pickle` 模組還具備一個透明化的、以 C 語言編寫的最" +"佳化工具。" #: ../../library/pickle.rst:1157 msgid "Examples" @@ -2228,7 +2325,7 @@ msgstr "範例" #: ../../library/pickle.rst:1159 msgid "" "For the simplest code, use the :func:`dump` and :func:`load` functions. ::" -msgstr "" +msgstr "最簡單的使用方式，調用 :func:`dump` 和 :func:`load` 函式。::" #: ../../library/pickle.rst:1161 msgid "" @@ -2245,10 +2342,22 @@ msgid "" " # Pickle the 'data' dictionary using the highest protocol available.\n" " pickle.dump(data, f, pickle.HIGHEST_PROTOCOL)" msgstr "" +"import pickle\n" +"\n" +"# 任意 pickle 支援的物件。\n" +"data = {\n" +" 'a': [1, 2.0, 3+4j],\n" +" 'b': (\"string\", b\"byte string\"),\n" +" 'c': {None, True, False}\n" +"}\n" +"\n" +"with open('data.pickle', 'wb') as f:\n" +" # 使用可用的最高協定來封裝 'data' 字典。\n" +" pickle.dump(data, f, pickle.HIGHEST_PROTOCOL)\n" #: ../../library/pickle.rst:1175 msgid "The following example reads the resulting pickled data. ::" -msgstr "" +msgstr "以下範例可以讀取前述程式所封裝的 pickle 資料。::" #: ../../library/pickle.rst:1177 msgid "" @@ -2259,6 +2368,11 @@ msgid "" " # have to specify it.\n" " data = pickle.load(f)" msgstr "" +"import pickle\n" +"\n" +"with open('data.pickle', 'rb') as f:\n" +" # 會自動檢測資料使用的協定版本，因此我們不需要手動指定。\n" +" data = pickle.load(f)" #: ../../library/pickle.rst:1191 msgid "Module :mod:`copyreg`" @@ -2266,7 +2380,7 @@ msgstr ":mod:`copyreg` 模組" #: ../../library/pickle.rst:1192 msgid "Pickle interface constructor registration for extension types." -msgstr "" +msgstr "註冊擴充型別的 Pickle 介面建構子。" #: ../../library/pickle.rst:1194 msgid "Module :mod:`pickletools`" @@ -2274,7 +2388,7 @@ msgstr ":mod:`pickletools` 模組" #: ../../library/pickle.rst:1195 msgid "Tools for working with and analyzing pickled data." -msgstr "" +msgstr "用於分析或處裡被封裝資料的工具。" #: ../../library/pickle.rst:1197 msgid "Module :mod:`shelve`" @@ -2282,7 +2396,7 @@ msgstr ":mod:`shelve` 模組" #: ../../library/pickle.rst:1198 msgid "Indexed databases of objects; uses :mod:`pickle`." -msgstr "" +msgstr "索引式資料庫；使用 :mod:`pickle` 實作。" #: ../../library/pickle.rst:1200 msgid "Module :mod:`copy`" @@ -2290,7 +2404,7 @@ msgstr ":mod:`copy` 模組" #: ../../library/pickle.rst:1201 msgid "Shallow and deep object copying." -msgstr "" +msgstr "物件的淺層或深度拷貝。" #: ../../library/pickle.rst:1203 msgid "Module :mod:`marshal`" @@ -2298,7 +2412,7 @@ msgstr ":mod:`marshal` 模組" #: ../../library/pickle.rst:1204 msgid "High-performance serialization of built-in types." -msgstr "" +msgstr "內建型別的高效能序列化。" #: ../../library/pickle.rst:1208 msgid "Footnotes" @@ -2306,25 +2420,29 @@ msgstr "註解" #: ../../library/pickle.rst:1209 msgid "Don't confuse this with the :mod:`marshal` module" -msgstr "" +msgstr "不要將此模組與 :mod:`marshal` 模組混淆" #: ../../library/pickle.rst:1211 msgid "" "This is why :keyword:`lambda` functions cannot be pickled: all :keyword:`!" "lambda` functions share the same name: ````." msgstr "" +"這就是為什麼 :keyword:`lambda` 函式無法被封裝：所有 :keyword:`!lambda` 函式共" +"享相同的名稱：````。" #: ../../library/pickle.rst:1214 msgid "" "The exception raised will likely be an :exc:`ImportError` or an :exc:" "`AttributeError` but it could be something else." msgstr "" +"拋出的例外應該是 :exc:`ImportError` 或 :exc:`AttributeError`，但也可能是其他" +"例外。" #: ../../library/pickle.rst:1217 msgid "" "The :mod:`copy` module uses this protocol for shallow and deep copying " "operations." -msgstr "" +msgstr ":mod:`copy` 模組使用此協定進行淺層及深層複製操作。" #: ../../library/pickle.rst:1220 msgid "" @@ -2333,6 +2451,9 @@ msgid "" "kind of newline characters occurs in persistent IDs, the resulting pickled " "data will become unreadable." msgstr "" +"協定 0 中限制僅能使用英文字母或數字字元來分配持久化 ID 是因為持久化 ID 是由換" +"行符號所分隔的。因此，如果持久化 ID 中出現任何形式的換行字元，將導致封裝資料" +"變得無法讀取。" #: ../../library/pickle.rst:12 msgid "persistence" @@ -2364,7 +2485,7 @@ msgstr "pickling" #: ../../library/pickle.rst:123 msgid "External Data Representation" -msgstr "External Data Representation（外部資料表示法）" +msgstr "External Data Representation（外部資料表現）" #: ../../library/pickle.rst:664 msgid "copy" From 10b5c6dd31160d1e860d224692488c5566b4141b Mon Sep 17 00:00:00 2001 From: "Raynor@GullU" Date: Mon, 30 Sep 2024 23:38:12 +0800 Subject: [PATCH 14/17] docs(library/pickle.po): Build succesful --- library/pickle.po | 55 +++++++++++++++++++++++++---------------------- 1 file changed, 29 insertions(+), 26 deletions(-) diff --git a/library/pickle.po b/library/pickle.po index 1f6b2b99c9..be51283dc1 100644 --- a/library/pickle.po +++ b/library/pickle.po @@ -96,8 +96,8 @@ msgid "" "pyc` files." msgstr "" "Python 有另一個比較原始的序列化模組叫 :mod:`marshal`，不過其設計目的是為了支" -"援 Python 的預編譯功能 :file:`.pyc` 的運作。總地來說，沒事不要用 :mod:" -"`marshal`。" +"援 Python 的預編譯功能 :file:`.pyc` 的運作。總地來說，請盡可能地使用 :mod:" +"`pickle`，沒事不要用 :mod:`marshal`。" #: ../../library/pickle.rst:57 msgid "" @@ -251,7 +251,7 @@ msgid "" "efficiently :doc:`compress ` pickled data." msgstr "" "以預設設定來說，:mod:`pickle` 使用相對緊湊的二進位形式來儲存資料。如果你需要" -"盡可能地縮小檔案大小，你可以\\\\ :doc:`壓縮 `\\\\ 封裝的資料。" +"盡可能地縮小檔案大小，你可以\\ :doc:`壓縮 `\\ 封裝的資料。" #: ../../library/pickle.rst:135 msgid "" @@ -412,8 +412,8 @@ msgid "" "Write the pickled representation of the object *obj* to the open :term:`file " "object` *file*. This is equivalent to ``Pickler(file, protocol).dump(obj)``." msgstr "" -"將被封裝成 pickle 形式的 *obj* 寫入到已開啟的\\\\ term:`檔案物件 ` *file*。這等效於\\\\ ``Pickler(file, protocol).dump(obj)``。" +"將被封裝成 pickle 形式的 *obj* 寫入到已開啟的\\ :term:`file object` *file*。" +"這等效於\\ ``Pickler(file, protocol).dump(obj)``。" #: ../../library/pickle.rst:222 msgid "" @@ -685,8 +685,11 @@ msgid "" "and can optionally return :data:`NotImplemented` to fallback on :attr:" "`dispatch_table`-registered reducers to pickle ``obj``." msgstr "" -"傳 :data:`NotImplemented` 以退回（fallback）並改為使用 :attr:" -"`dispatch_table` 中登錄的縮減方法來封裝 ``obj``。" +"一個可以在 :class:`Pickler` 子類別中被定義的縮減器（reducer）。這個方法的優先" +"度高於任何其他 :attr:`分派表 ` 中的縮減器。他應該要有和 :" +"meth:`~object.__reduce__` 方法相同的函數界面，且可以可選地回傳 :data:" +"`NotImplemented` 以退回（fallback）使用 :attr:`分派表 ` 中登" +"錄的縮減方法來封裝 ``obj``。" #: ../../library/pickle.rst:379 msgid "For a detailed example, see :ref:`reducer_override`." @@ -744,7 +747,7 @@ msgid "" "datetime`, :class:`~datetime.date` and :class:`~datetime.time` pickled by " "Python 2." msgstr "" -"可選引數 *fix_imports*，*encoding* 和 *errors* 用來控制 Python 2 pickle 資料" +"可選引數 *fix_imports*、*encoding* 和 *errors* 用來控制 Python 2 pickle 資料" "的相容性支援。如果 *fix_imports* 為 true，則 pickle 模組會嘗試將舊的 Python " "2 模組名稱映射到 Python 3 中使用的新名稱。*encoding* 和 *errors* 告訴 pickle " "模組如何解碼由 Python 2 pickle 封裝的 8 位元字串實例；*encoding* 和 *errors* " @@ -760,9 +763,9 @@ msgid "" "*buffer_callback* argument was ``None`` when a :class:`Pickler` was " "instantiated (or when :func:`dump` or :func:`dumps` was called)." msgstr "" -"如果 *buffers* 是 ``None``（預設值），那麼去序列化所需的所有資料都必須已經包" -"含在 pickle 串流中。這意味著當初在建立對應的 :class:`Pickler` 時（或在呼叫 :" -"func:`dump` 或 :func:`dumps` 時）*buffer_callback* 引數必須為 ``None``。" +"如果 *buffers* 是 ``None``\\ （預設值），那麼去序列化所需的所有資料都必須已經" +"包含在 pickle 串流中。這意味著當初在建立對應的 :class:`Pickler` 時（或在呼" +"叫 :func:`dump` 或 :func:`dumps` 時）*buffer_callback* 引數必須為 ``None``。" #: ../../library/pickle.rst:424 msgid "" @@ -772,8 +775,8 @@ msgid "" "the *buffer_callback* of a Pickler object." msgstr "" "如果 *buffers* 不是 ``None``，則其應該是一個可疊代物件，內含數個支援緩衝區的" -"物件，並且每當 pickle 串流引用一個 :ref:`帶外 ` 緩衝區視圖時將會" -"被照順序消耗。這些緩衝資料當初建立時應已按照順序給定予 Pickler 物件中的 " +"物件，並且每當 pickle 串流引用一個\\ :ref:`帶外 `\\ 緩衝區視圖時" +"將會被照順序消耗。這些緩衝資料當初建立時應已按照順序給定予 Pickler 物件中的 " "*buffer_callback*。" #: ../../library/pickle.rst:434 @@ -816,7 +819,7 @@ msgid "" "`pickle-restrict` for details." msgstr "" "子類別可以覆寫此方法以控制可以載入哪些類型的物件、以及如何載入它們，從而潛在" -"地降低安全性風險。詳情請參考 :ref:`pickle-restrict`。" +"地降低安全性風險。詳情請參考\\ :ref:`pickle-restrict`。" #: ../../library/pickle.rst:460 msgid "" @@ -836,8 +839,8 @@ msgid "" "object` or a N-dimensional array." msgstr "" "一個表示了含有可封裝數據緩衝區的包裝函數（wrapper function）。*buffer* 必須是" -"一個 :ref:`提供緩衝區 ` 的物件，例如一個 :term:`類位元組物件" -"（bytes-like object）` 或 N 維陣列。" +"一個 :ref:`提供緩衝區 ` 的物件，例如一個 :term:`類位元組物件 " +"` 或 N 維陣列。" #: ../../library/pickle.rst:468 msgid "" @@ -855,9 +858,9 @@ msgid "" "oob>`." msgstr "" ":class:`PickleBuffer` 物件僅能由 5 版或以上的 pickle 協定進行封裝。該物件亦能" -"被作為帶外資料來進行:ref:`帶外資料序列化 `" +"被作為帶外資料來進行\\ :ref:`帶外資料序列化 `" -# SkyLull: oh boy... 好多術語... +# SkyLull: oh... 好多術語... # format B: https://learn.microsoft.com/zh-tw/dotnet/standard/base- # types/standard-numeric-format-strings#BFormatString # C-contiguous, Fortran-contiguous: https://stackoverflow.com/a/26999092 @@ -1304,7 +1307,7 @@ msgstr "" "可選項。一個用來提供連續項目的疊代器（而非序列）。這些項目將個別透過 ``obj." "append(item)`` 方法或成批次地透過 ``obj.extend(list_of_items)`` 方法被附加到" "物件中。主要用於串列（list）子類別，但只要其他類別具有相應的 :ref:`append 和 " -"extend 方法 `和相同的輸入特徵（signature）就也可以使用。 " +"extend 方法 `\\ 和相同的輸入特徵（signature）就也可以使用。 " "（如何選擇使用 :meth:`!append` 或 :meth:`!extend` 方法將取決於所選用的 " "pickle 協定版本以及要附加的項目數量，因此必須同時支援這兩種方法。）" @@ -1988,8 +1991,8 @@ msgid "" "graph. Buffers accumulated by the *buffer_callback* will not see their data " "copied into the pickle stream, only a cheap marker will be inserted." msgstr "" -"傳送端需要傳遞一個調用緩衝區的回呼函數給 :class:`Pickler`（或 :func:`dump` " -"或 :func:`dumps` 函數）的 *buffer_callback* 引數，使每次生成 :class:" +"傳送端需要傳遞一個調用緩衝區的回呼函數給 :class:`Pickler`\\ （或 :func:" +"`dump` 或 :func:`dumps` 函數）的 *buffer_callback* 引數，使每次生成 :class:" "`PickleBuffer` 時，該物件在處理物件圖時能被呼叫。除了一個簡易標記以外，由 " "*buffer_callback* 累積的緩衝區資料不會被複製到 pickle 串流中。" @@ -2003,11 +2006,11 @@ msgid "" "reconstructors of the objects whose pickling produced the original :class:" "`PickleBuffer` objects." msgstr "" -"接收端需要傳遞一個緩衝區物件給 :class:`Unpickler`（或 :func:`load` 或 :func:" -"`loads` 函式）的 *buffers* 引數。該物件須是一個可疊代的（iterable）緩衝區" -"（buffer）物件，其中包含傳遞給 *buffer_callback* 的緩衝區物件。這個可疊代物件" -"的緩衝區順序應該與它們當初被封裝時傳遞給 *buffer_callback* 的順序相同。這些緩" -"衝區將提供物件重建所需的資料，以使重建器能還原出那個當時產生了 :class:" +"接收端需要傳遞一個緩衝區物件給 :class:`Unpickler`\\ （或 :func:`load` 或 :" +"func:`loads` 函式）的 *buffers* 引數。該物件須是一個可疊代的（iterable）緩衝" +"區（buffer）物件，其中包含傳遞給 *buffer_callback* 的緩衝區物件。這個可疊代物" +"件的緩衝區順序應該與它們當初被封裝時傳遞給 *buffer_callback* 的順序相同。這些" +"緩衝區將提供物件重建所需的資料，以使重建器能還原出那個當時產生了 :class:" "`PickleBuffer` 的物件。" #: ../../library/pickle.rst:999 From 4dd1468cc4377df739ea402f3d701d06a00cedf8 Mon Sep 17 00:00:00 2001 From: "Raynor@GullU" Date: Mon, 14 Oct 2024 13:08:13 +0800 Subject: [PATCH 15/17] docs(library/pickle.po): fixes of all suggestions before 10/14 --- library/pickle.po | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/library/pickle.po b/library/pickle.po index 78f566f976..da84ddf558 100644 --- a/library/pickle.po +++ b/library/pickle.po @@ -128,7 +128,7 @@ msgid "" msgstr "" "這對遞迴物件和物件共用都有影響。遞迴物件是指包含自我參照的物件。這些情況在 " "marshal 模組中不會被處理，若嘗試使用 marshal 處理遞迴物件會導致 Python 直譯器" -"崩潰。物件共用發生在序列化的物件階層中，不同位置對同一物件有多個參照時。:mod:" +"崩潰。物件共用發生在序列化的物件階層中、不同位置對同一物件有多個參照時。:mod:" "`pickle` 只會儲存這個被參照的物件一次，並確保所有其他參照指向這個主要的版本。" "共用的物件會保持共用，這對於可變（mutable）物件來說非常重要。" @@ -240,7 +240,7 @@ msgid "" "Python programs may not be able to reconstruct pickled Python objects." msgstr "" ":mod:`pickle` 使用的資料格式是針對 Python 而設計的。好處是他不會受到外部標準" -"（像是 JSON 或 XDR，而 XDR 無法紀錄指標共用）的限制；不過這也代表其他不是 " +"（像是 JSON，無法紀錄指標共用）的限制；不過這也代表其他不是 " "Python 的程式可能無法重建 pickle 封裝的 Python 物件。" #: ../../library/pickle.rst:131 @@ -267,7 +267,7 @@ msgid "" "The higher the protocol used, the more recent the version of Python needed " "to read the pickle produced." msgstr "" -"截至目前為止，共有六種不同版本的協定可用於封裝 pickle。數字越大版本代表你需" +"截至目前為止，共有六種不同版本的協定可用於封裝 pickle。數字越大版本代表你需" "要使用越新的 Python 版本來拆封相應的 pickle 封裝。" #: ../../library/pickle.rst:143 From 0d55be1c2948aca3ae21521adc7a0ad2eaac3a16 Mon Sep 17 00:00:00 2001 From: "Raynor@GullU" Date: Mon, 21 Oct 2024 00:31:09 +0800 Subject: [PATCH 16/17] docs(library/pickle.po): resolve all of the suggestions before 10/19 --- library/pickle.po | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/library/pickle.po b/library/pickle.po index da84ddf558..4dddef77bd 100644 --- a/library/pickle.po +++ b/library/pickle.po @@ -411,7 +411,7 @@ msgid "" "Write the pickled representation of the object *obj* to the open :term:`file " "object` *file*. This is equivalent to ``Pickler(file, protocol).dump(obj)``." msgstr "" -"將被封裝成 pickle 形式的 *obj* 寫入到已開啟的\\ :term:`file object` *file*。" +"將被封裝成 pickle 形式的物件 *obj* 寫入到已開啟的\\ :term:`file object` *file*。" "這等效於\\ ``Pickler(file, protocol).dump(obj)``。" #: ../../library/pickle.rst:222 @@ -432,7 +432,7 @@ msgid "" "Return the pickled representation of the object *obj* as a :class:`bytes` " "object, instead of writing it to a file." msgstr "" -"將被封裝為 pickle 形式的 *obj* 以 :class:`bytes` 類別回傳，而非寫入進檔案。" +"將被封裝為 pickle 形式的物件 *obj* 以 :class:`bytes` 類別回傳，而非寫入進檔案。" #: ../../library/pickle.rst:233 msgid "" From 44db333887905ab1598da897b96f534f529f482d Mon Sep 17 00:00:00 2001 From: "Raynor@GullU" Date: Thu, 31 Oct 2024 21:55:27 +0800 Subject: [PATCH 17/17] docs(library/pickle.po): update the translation of `function signature` --- library/pickle.po | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/library/pickle.po b/library/pickle.po index 4dddef77bd..370cbe643d 100644 --- a/library/pickle.po +++ b/library/pickle.po @@ -1303,8 +1303,7 @@ msgstr "" "`~object.__dict__` 屬性中。" # SkyLull: [T] -# signature: https://stackoverflow.com/questions/72788932/what-is-a-function- -# signature -> 輸入特徵 +# signature: https://jo-jo.medium.com/c-c-%E5%B9%BC%E5%B9%BC%E7%8F%AD-%E7%B0%BD%E7%AB%A0signature-fa9b04e1a3e2 #: ../../library/pickle.rst:715 msgid "" "Optionally, an iterator (and not a sequence) yielding successive items. " @@ -1319,8 +1318,8 @@ msgstr "" "可選項。一個用來提供連續項目的疊代器（而非序列）。這些項目將個別透過 ``obj." "append(item)`` 方法或成批次地透過 ``obj.extend(list_of_items)`` 方法被附加到" "物件中。主要用於串列（list）子類別，但只要其他類別具有相應的 :ref:`append 和 " -"extend 方法 `\\ 和相同的輸入特徵（signature）就也可以使用。 " -"（如何選擇使用 :meth:`!append` 或 :meth:`!extend` 方法將取決於所選用的 " +"extend 方法 `\\ 以及相同的函式簽章（signature）就也可以使用。 " +"（是否會調用 :meth:`!append` 或 :meth:`!extend` 方法將取決於所選用的 " "pickle 協定版本以及要附加的項目數量，因此必須同時支援這兩種方法。）" #: ../../library/pickle.rst:725 @@ -1342,7 +1341,7 @@ msgid "" "method. If not ``None``, this callable will have priority over ``obj``'s :" "meth:`__setstate__`." msgstr "" -"可選項。一個具有 ``(obj, state)`` 輸入特徵（signature）的可呼叫物件。該物件允" +"可選項。一個具有 ``(obj, state)`` 函式簽章（signature）的可呼叫物件。該物件允" "許使用者以可編寫的邏輯，而不是物件 ``obj`` 預設的 :meth:`__setstate__` 靜態方" "法去控制特定物件的狀態更新方式。如果這個物件不是 ``None``，這個物件的呼叫優先" "權將優於物件 ``obj`` 的 :meth:`__setstate__`。"