docs(library/pickle.po): editing, up to line 1600

Author: SkyLull

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 方法 <typesseq-common>`就也可以使用。 （如何選擇使用 :meth:`!append` "
-"或 :meth:`!extend` 方法將取決於所選用的 pickle 協定版本以及要附加的項目數量，"
-"因此必須同時支援這兩種方法。）"
+"extend 方法 <typesseq-common>`和相同的輸入特徵（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,19 +1388,27 @@ 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 ""
 "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 ""
+"要拆封外部物件，拆封器（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 ""